feat(runtime): adopt Relayfile-VFS as the canonical integration-client style#92
Open
khaliqgant wants to merge 3 commits into
Open
feat(runtime): adopt Relayfile-VFS as the canonical integration-client style#92khaliqgant wants to merge 3 commits into
khaliqgant wants to merge 3 commits into
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughConverts integration clients from direct HTTP to a Relayfile VFS: adds a shared filesystem-backed transport, relocates/standardizes WorkforceIntegrationError, rewrites GitHub client to use mounted draft files, and implements Linear, Slack, Notion, and Jira clients with filesystem-backed tests; updates weekly-digest docs and example code to the writeback flow. ChangesRelayfile VFS integration clients (single cohesive cohort)
Sequence DiagramsequenceDiagram
participant Handler as Handler / Agent
participant VFS as Relayfile Mount (VFS)
participant Worker as Writeback Worker
participant API as External API (GitHub/Linear/etc.)
Handler->>VFS: writeJsonFile(provider, path, draft)
VFS-->>Handler: write completed (optional immediate receipt)
Note over Worker: Worker polls VFS for drafts
Worker->>VFS: listJsonFiles(provider, drafts)
VFS-->>Worker: [draft1, ...]
Worker->>VFS: readJsonFile(draft path)
VFS-->>Worker: draft payload
Worker->>API: perform API call (create/update/etc.)
API-->>Worker: API response (id, url, meta)
Worker->>VFS: write receipt/metadata to canonical path
VFS-->>Worker: write complete
Handler->>VFS: readJsonFile(canonical path) %% optional read for metadata
VFS-->>Handler: metadata/receipt
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
This was referenced May 12, 2026
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
Comment on lines
+156
to
+162
| await writeJsonFile( | ||
| opts, | ||
| 'github', | ||
| 'upsertIssue.update', | ||
| `${issueDir}/${encodeSegment(existing.value.number)}.json`, | ||
| { title: args.title, body: args.body, labels: args.labels } | ||
| ); |
Contributor
There was a problem hiding this comment.
🔴 upsertIssue update overwrites the issue file, losing the number field needed for subsequent match lookups
When upsertIssue finds an existing issue and updates it (line 156–162), it writes { title, body, labels } to the canonical <number>.json file via writeJsonFile. This completely replaces the file's previous content, which included number and html_url metadata. On the next upsertIssue call, listJsonFiles reads back the file as a GithubIssueFile but number is now undefined. The match check at line 154 (issue.value.title === args.matchTitle && issue.value.number) fails because number is falsy, so the code falls through to this.createIssue(args) and creates a duplicate issue. This breaks the weekly-digest agent's core use case — every run after the first update creates a new issue instead of updating the existing one.
Trace of the data loss
Before update, 7.json contains:
{"number": 7, "title": "Weekly digest — 2026-W20", "html_url": "https://..."}After line 161 writes, 7.json becomes:
{"title": "Weekly digest — 2026-W20", "body": "refreshed", "labels": ["weekly-digest"]}number and html_url are gone. Next lookup at line 154 sees number: undefined → no match → creates duplicate.
Suggested change
| await writeJsonFile( | |
| opts, | |
| 'github', | |
| 'upsertIssue.update', | |
| `${issueDir}/${encodeSegment(existing.value.number)}.json`, | |
| { title: args.title, body: args.body, labels: args.labels } | |
| ); | |
| await writeJsonFile( | |
| opts, | |
| 'github', | |
| 'upsertIssue.update', | |
| `${issueDir}/${encodeSegment(existing.value.number)}.json`, | |
| { number: existing.value.number, html_url: existing.value.html_url, url: existing.value.url, title: args.title, body: args.body, labels: args.labels } | |
| ); |
Was this helpful? React with 👍 or 👎 to provide feedback.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@examples/weekly-digest/README.md`:
- Around line 60-62: The RELAYFILE_MOUNT_ROOT environment variable is currently
scoped only to the echo process and not passed to the downstream node runner;
move the RELAYFILE_MOUNT_ROOT assignment so it applies to the node process
(i.e., export or place the variable before invoking node
/tmp/wf-weekly-digest/runner.mjs) so that runner.mjs can read
RELAYFILE_MOUNT_ROOT when processing the piped JSON from echo.
In `@packages/runtime/src/clients/github.ts`:
- Around line 107-129: The comment() and createIssue() (and the create-branch
path of upsertIssue()) currently return Relayfile paths or zero when
writeJsonFile() yields no receipt; update these methods to require a valid
writeback receipt before returning GitHub metadata by checking result.receipt
(and specific fields like receipt.created/receipt.id/receipt.url) and throw a
clear error if absent instead of returning result.path or 0; ensure the same
receipt-mandatory validation and error handling is applied in upsertIssue()’s
create branch so callers only receive real GitHub IDs/URLs.
- Around line 154-170: The upsertIssue implementation currently finds issues by
comparing stored.title to args.matchTitle but immediately rewrites the title to
args.title, so subsequent calls become non-idempotent; update the matching logic
inside upsertIssue (the issues.find predicate) to match either
existing.value.title === args.matchTitle OR existing.value.title === args.title
(or, if available, prefer matching by a stable identifier like
existing.value.number or args.number), so the same issue is found even after the
title is changed and createIssue is not called again; ensure you still use
existing.value.number when calling writeJsonFile and returning the upsert
result.
- Around line 174-189: The code is re-encoding the directory name returned by
findNumberSegment (pullSegment) which can double-escape slashes; instead build
pullRoot using pullSegment verbatim (i.e., remove encodeSegment(pullSegment)) so
subsequent reads via readJsonFile/readTextFile use the actual discovered
directory name; keep encoding only where you intentionally encode the numeric
target (e.g., encodeSegment(target.number)) if needed for fallbacks.
In `@packages/runtime/src/clients/jira.ts`:
- Around line 54-62: The transition method accepts a transition id that may be
empty after trimming; before calling writeJsonFile (and when computing id in
transition), validate that id is a non-empty string (after trim) and throw or
return a clear error if empty to avoid writing invalid drafts; update the logic
in async transition (and any helper that computes id) to trim, check id.length >
0, and bail with a descriptive error instead of calling writeJsonFile or
creating the draft via draftFile('create transition').
In `@packages/runtime/src/clients/notion.ts`:
- Around line 48-50: The createPage return currently sets id to
result.receipt?.created ?? result.receipt?.id ?? '' which can produce an empty
string; change it to return undefined instead of '' so callers don't receive a
bogus id. Update the returned object in createPage to use
result.receipt?.created ?? result.receipt?.id ?? undefined for the id field (and
adjust any type if needed) so the absence of a receipt yields undefined rather
than an empty string.
- Around line 29-33: readDatabaseId currently throws a generic Error on invalid
parent database id; replace that with throwing a WorkforceIntegrationError so
failures follow the integration error contract and carry retry metadata. Update
the readDatabaseId function to import/use WorkforceIntegrationError (or the
existing integration error class) and throw a WorkforceIntegrationError with a
descriptive message like "Notion createPage file writeback requires
parent.database_id" and include any required retry/metadata fields per
WorkforceIntegrationError's constructor so callers (createPage path) get
consistent error type and retry behavior.
In `@packages/runtime/src/clients/request.ts`:
- Around line 225-239: The loop in waitForReceipt reads/parses the file before
checking fire-and-forget mode, allowing payloads with top-level id/path/created
to be misinterpreted as receipts; modify waitForReceipt so it checks whether
writeback is disabled (client.writebackTimeoutMs <= 0) or the deadline has
already passed before calling readCurrentJson, and only parse/validate the JSON
when writeback is enabled and there is remaining time (use timeoutMs/deadline or
client.writebackTimeoutMs and client.writebackPollMs in the do/while loop).
Ensure the early-return behavior for fire-and-forget remains (return undefined
immediately when timeoutMs <= 0) and preserve the poll delay logic
(client.writebackPollMs) and the final deadline comparison (Date.now() <
deadline) around the parse step.
In `@packages/runtime/src/clients/slack.ts`:
- Around line 49-80: The post and dm methods currently allow empty channel/user
or empty text and write malformed drafts; add local validation at the start of
SlackClient.post and SlackClient.dm (and optionally SlackClient.reply) to reject
empty identifiers and empty text similar to parseThreadRef: verify channel/user
(and for reply the parsed thread.channel and thread.ts) are non-empty and that
text is a non-blank string, and throw a clear Error (or return a rejected
Promise) before calling writeJsonFile; reuse encodeSegment/tsPathSegment only
after validation and keep the existing receipt extraction logic unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 99464476-b9fe-4e7c-8050-902e4384afc0
📒 Files selected for processing (18)
examples/weekly-digest/README.mdexamples/weekly-digest/agent.tspackages/runtime/src/clients/errors.tspackages/runtime/src/clients/github.test.tspackages/runtime/src/clients/github.tspackages/runtime/src/clients/index.tspackages/runtime/src/clients/jira.test.tspackages/runtime/src/clients/jira.tspackages/runtime/src/clients/linear.test.tspackages/runtime/src/clients/linear.tspackages/runtime/src/clients/notion.test.tspackages/runtime/src/clients/notion.tspackages/runtime/src/clients/request.tspackages/runtime/src/clients/slack.test.tspackages/runtime/src/clients/slack.tspackages/runtime/src/errors.tspackages/runtime/src/index.tspackages/runtime/src/types.ts
💤 Files with no reviewable changes (1)
- packages/runtime/src/clients/errors.ts
Comment on lines
+107
to
+129
| const result = await writeJsonFile( | ||
| opts, | ||
| 'github', | ||
| 'comment', | ||
| `${repoRoot(target.owner, target.repo)}/issues/${encodeSegment(target.number)}/comments/${draftFile('create comment')}`, | ||
| { body } | ||
| ); | ||
| return { | ||
| id: result.receipt?.created ?? result.receipt?.id ?? result.path, | ||
| url: result.receipt?.url ?? result.path | ||
| }; | ||
| }, | ||
|
|
||
| async createIssue(args) { | ||
| const out = await request<{ number: number; html_url: string }>('createIssue', { | ||
| method: 'POST', | ||
| pathname: `/repos/${args.owner}/${args.repo}/issues`, | ||
| body: { | ||
| title: args.title, | ||
| body: args.body, | ||
| ...(args.labels ? { labels: args.labels } : {}) | ||
| } | ||
| }); | ||
| return { number: out.number, url: out.html_url }; | ||
| const result = await writeJsonFile( | ||
| opts, | ||
| 'github', | ||
| 'createIssue', | ||
| `${repoRoot(args.owner, args.repo)}/issues/${draftFile('create issue')}`, | ||
| { title: args.title, body: args.body, labels: args.labels } | ||
| ); | ||
| const number = Number(result.receipt?.created ?? result.receipt?.id ?? 0); | ||
| return { number: Number.isFinite(number) ? number : 0, url: result.receipt?.url ?? result.path }; |
There was a problem hiding this comment.
Require a writeback receipt before returning GitHub metadata.
If writeJsonFile() completes without a receipt, comment() returns a Relayfile path as the id/url and createIssue() returns number: 0. That looks like a successful GitHub mutation but gives callers unusable identifiers and leaks mount internals. Please fail fast here, or make receipt polling mandatory for methods that promise GitHub IDs/URLs. This also affects the create branch of upsertIssue() at Line 169.
Also applies to: 169-170
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/runtime/src/clients/github.ts` around lines 107 - 129, The comment()
and createIssue() (and the create-branch path of upsertIssue()) currently return
Relayfile paths or zero when writeJsonFile() yields no receipt; update these
methods to require a valid writeback receipt before returning GitHub metadata by
checking result.receipt (and specific fields like
receipt.created/receipt.id/receipt.url) and throw a clear error if absent
instead of returning result.path or 0; ensure the same receipt-mandatory
validation and error handling is applied in upsertIssue()’s create branch so
callers only receive real GitHub IDs/URLs.
Comment on lines
+154
to
+170
| const existing = issues.find((issue) => issue.value.title === args.matchTitle && issue.value.number); | ||
| if (existing?.value.number) { | ||
| await writeJsonFile( | ||
| opts, | ||
| 'github', | ||
| 'upsertIssue.update', | ||
| `${issueDir}/${encodeSegment(existing.value.number)}.json`, | ||
| { title: args.title, body: args.body, labels: args.labels } | ||
| ); | ||
| return { | ||
| number: existing.value.number, | ||
| url: existing.value.html_url ?? existing.value.url ?? '', | ||
| created: false | ||
| }; | ||
| } | ||
| const created = await request<{ number: number; html_url: string }>('upsertIssue.create', { | ||
| method: 'POST', | ||
| pathname: `/repos/${args.owner}/${args.repo}/issues`, | ||
| body: { | ||
| title: args.matchTitle === args.title ? args.title : args.matchTitle, | ||
| body: args.body, | ||
| ...(args.labels ? { labels: args.labels } : {}) | ||
| } | ||
| }); | ||
| return { number: created.number, url: created.html_url, created: true }; | ||
| const created = await this.createIssue(args); | ||
| return { ...created, created: true }; |
There was a problem hiding this comment.
upsertIssue() stops being idempotent when title !== matchTitle.
Line 154 only matches the current stored title against args.matchTitle, but Lines 156-161 immediately rewrite that title to args.title. A second call with the same inputs will no longer find the previously updated issue and will fall through to createIssue(), producing duplicates. Match against both titles, or use a stable key that survives title changes.
💡 Minimal fix
- const existing = issues.find((issue) => issue.value.title === args.matchTitle && issue.value.number);
+ const candidateTitles = new Set([args.matchTitle, args.title]);
+ const existing = issues.find(
+ (issue) => issue.value.number && issue.value.title && candidateTitles.has(issue.value.title)
+ );🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/runtime/src/clients/github.ts` around lines 154 - 170, The
upsertIssue implementation currently finds issues by comparing stored.title to
args.matchTitle but immediately rewrites the title to args.title, so subsequent
calls become non-idempotent; update the matching logic inside upsertIssue (the
issues.find predicate) to match either existing.value.title === args.matchTitle
OR existing.value.title === args.title (or, if available, prefer matching by a
stable identifier like existing.value.number or args.number), so the same issue
is found even after the title is changed and createIssue is not called again;
ensure you still use existing.value.number when calling writeJsonFile and
returning the upsert result.
Comment on lines
+48
to
+50
| return { | ||
| id: result.receipt?.created ?? result.receipt?.id ?? '', | ||
| url: result.receipt?.url, |
There was a problem hiding this comment.
Avoid returning an empty id from createPage.
When no receipt is present (common in fire-and-forget mode), id becomes '', which breaks the method contract for callers expecting a usable identifier.
Suggested fix
return {
- id: result.receipt?.created ?? result.receipt?.id ?? '',
+ id: result.receipt?.created ?? result.receipt?.id ?? result.path,
url: result.receipt?.url,
properties
};🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/runtime/src/clients/notion.ts` around lines 48 - 50, The createPage
return currently sets id to result.receipt?.created ?? result.receipt?.id ?? ''
which can produce an empty string; change it to return undefined instead of ''
so callers don't receive a bogus id. Update the returned object in createPage to
use result.receipt?.created ?? result.receipt?.id ?? undefined for the id field
(and adjust any type if needed) so the absence of a receipt yields undefined
rather than an empty string.
Comment on lines
+49
to
+80
| async post(channel, text) { | ||
| const result = await writeJsonFile( | ||
| opts, | ||
| 'slack', | ||
| 'post', | ||
| `/slack/channels/${encodeSegment(channel)}/messages/${draftFile('create message')}`, | ||
| { text } | ||
| ); | ||
| return { channel, ts: result.receipt?.created ?? result.receipt?.id ?? '' }; | ||
| }, | ||
|
|
||
| async reply(threadTs, text) { | ||
| const thread = parseThreadRef(threadTs); | ||
| const result = await writeJsonFile( | ||
| opts, | ||
| 'slack', | ||
| 'reply', | ||
| `/slack/channels/${encodeSegment(thread.channel)}/messages/${tsPathSegment(thread.ts)}/replies/${draftFile('create reply')}`, | ||
| { text } | ||
| ); | ||
| return { channel: thread.channel, ts: result.receipt?.created ?? result.receipt?.id ?? '' }; | ||
| }, | ||
|
|
||
| async dm(user, text) { | ||
| const result = await writeJsonFile( | ||
| opts, | ||
| 'slack', | ||
| 'dm', | ||
| `/slack/users/${encodeSegment(user)}/messages/${draftFile('create dm')}`, | ||
| { text } | ||
| ); | ||
| return { channel: user, ts: result.receipt?.created ?? result.receipt?.id ?? '' }; |
There was a problem hiding this comment.
Add non-empty input guards for post/dm payload and identifiers.
post('', '...'), dm('', '...'), or blank text currently writes malformed drafts instead of failing fast. Add local validation mirroring parseThreadRef behavior.
Suggested fix
export function createSlackClient(opts: IntegrationClientOptions): SlackClient {
+ const requireNonEmpty = (operation: 'post' | 'reply' | 'dm', field: string, value: string): string => {
+ const trimmed = value.trim();
+ if (!trimmed) {
+ throw new WorkforceIntegrationError({
+ provider: 'slack',
+ operation,
+ cause: new Error(`Slack ${operation} ${field} must be non-empty`),
+ retryable: false
+ });
+ }
+ return trimmed;
+ };
+
return {
async post(channel, text) {
+ const safeChannel = requireNonEmpty('post', 'channel', channel);
+ const safeText = requireNonEmpty('post', 'text', text);
const result = await writeJsonFile(
opts,
'slack',
'post',
- `/slack/channels/${encodeSegment(channel)}/messages/${draftFile('create message')}`,
- { text }
+ `/slack/channels/${encodeSegment(safeChannel)}/messages/${draftFile('create message')}`,
+ { text: safeText }
);
- return { channel, ts: result.receipt?.created ?? result.receipt?.id ?? '' };
+ return { channel: safeChannel, ts: result.receipt?.created ?? result.receipt?.id ?? '' };
},
@@
async dm(user, text) {
+ const safeUser = requireNonEmpty('dm', 'user', user);
+ const safeText = requireNonEmpty('dm', 'text', text);
const result = await writeJsonFile(
opts,
'slack',
'dm',
- `/slack/users/${encodeSegment(user)}/messages/${draftFile('create dm')}`,
- { text }
+ `/slack/users/${encodeSegment(safeUser)}/messages/${draftFile('create dm')}`,
+ { text: safeText }
);
- return { channel: user, ts: result.receipt?.created ?? result.receipt?.id ?? '' };
+ return { channel: safeUser, ts: result.receipt?.created ?? result.receipt?.id ?? '' };
}
};
}🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/runtime/src/clients/slack.ts` around lines 49 - 80, The post and dm
methods currently allow empty channel/user or empty text and write malformed
drafts; add local validation at the start of SlackClient.post and SlackClient.dm
(and optionally SlackClient.reply) to reject empty identifiers and empty text
similar to parseThreadRef: verify channel/user (and for reply the parsed
thread.channel and thread.ts) are non-empty and that text is a non-blank string,
and throw a clear Error (or return a rejected Promise) before calling
writeJsonFile; reuse encodeSegment/tsPathSegment only after validation and keep
the existing receipt extraction logic unchanged.
khaliqgant
added a commit
that referenced
this pull request
May 12, 2026
Aligns the MCP server with the runtime's new client shape from #92. Before: the integration tools called createGithubClient({ token }) using WORKFORCE_INTEGRATION_GITHUB_TOKEN. That signature no longer exists in the runtime now that github speaks Relayfile-VFS, so the MCP package would fail to compile once #92 lands. Config (config.ts) - WorkforceMcpConfig drops `providerTokens`. The MCP server is no longer the place to hold provider PATs — Relayfile holds the credentials and the writeback worker uses them. - New `relayfileMountRoot` field, populated from RELAYFILE_MOUNT_ROOT (with RELAYFILE_ROOT as a legacy alias). The workforce runtime sets these env vars automatically when it spawns the harness via ctx.harness.run. - New `writebackTimeoutMs` field (default 30s, overridable via WORKFORCE_WRITEBACK_TIMEOUT_MS). Passed straight through to integration clients so handlers that need a synchronous receipt pay the same wait the runtime would. Integration dispatcher (tools/integrations.ts) - resolveGithub() now constructs createGithubClient with { relayfileMountRoot, writebackTimeoutMs } from config instead of a token. Refuses to construct when the mount root is missing with a message pointing at the runtime contract. Tests - config.test exercises RELAYFILE_MOUNT_ROOT (+ RELAYFILE_ROOT alias) and WORKFORCE_WRITEBACK_TIMEOUT_MS overrides. - integrations.test now writes against a tempdir mount and reads the resulting draft JSON file back to assert the canonical shape Relayfile expects. Covers happy path, missing-mount-root failure, postReview enum validation, and field-pointed errors. - server.test loads config with RELAYFILE_MOUNT_ROOT instead of a github PAT. - workflow.test + memory.test drop the obsolete providerTokens fixture key. 23 mcp-workforce tests pass (up from 21). PR base flips from main to feat/integrations-vfs (PR #92) since the new client shape lives there. Auto-rebases to main when #92 merges. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
khaliqgant
force-pushed
the
feat/integrations-vfs
branch
from
efb115b to
1f8dcdb
Compare
There was a problem hiding this comment.
Actionable comments posted: 10
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
packages/cli/src/cli.ts (1)
106-123:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix the Codex mount description in
--help.This block still says Codex sessions never mount and ignore
--install-in-repo, butdecideCleanMode()and the updated tests make Codex default to the sandbox mount and use--install-in-repoas the opt-out. The current help text points users to the opposite behavior.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/cli/src/cli.ts` around lines 106 - 123, The help text for the "agent [flags] <persona>" command is incorrect about Codex mounting; update the description to say Codex sessions now default to the sandbox mount and that --install-in-repo opts out (i.e., disengages the sandbox and installs skills into the repo) to match decideCleanMode() and tests. Edit the help string surrounding the --install-in-repo flag in the agent help block so it references Codex using the sandbox by default and that the flag disables that behavior.packages/workload-router/src/index.ts (1)
182-199:⚠️ Potential issue | 🟠 Major | ⚡ Quick winReject cross-harness overrides instead of patching only
harness.
usePersona(..., { harness: 'codex' })can now return a selection whosemodel,harnessSettings, and sidecar fields still belong to the original harness. With tiers gone there's no alternate runtime to swap in, so this produces selections that are internally inconsistent and not safely launchable.Suggested fix
export function useSelection( baseSelection: PersonaSelection, options: { harness?: Harness; installRoot?: string; repoRoot?: string } = {} ): PersonaContext { - const effectiveHarness = options.harness ?? baseSelection.harness; - const selection = - effectiveHarness === baseSelection.harness - ? baseSelection - : { ...baseSelection, harness: effectiveHarness }; + if (options.harness && options.harness !== baseSelection.harness) { + throw new Error( + `Cannot override harness from ${baseSelection.harness} to ${options.harness}; ` + + 'resolve or construct a selection for the target harness instead.' + ); + } + const effectiveHarness = baseSelection.harness; + const selection = baseSelection;🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/workload-router/src/index.ts` around lines 182 - 199, The function useSelection currently allows options.harness to override only the harness field but leaves model, harnessSettings, and sidecar from the original PersonaSelection, producing inconsistent selections; instead, add an early guard in useSelection that if options.harness is provided and differs from baseSelection.harness you reject it (throw a clear error or return a failure) rather than patching the object, and only proceed when options.harness is undefined or identical to baseSelection.harness; keep the rest of the logic (selection creation and calls to materializeSkillsFor and materializeSkills) unchanged but ensure the new guard runs before constructing selection or calling materializeSkillsFor/materializeSkills so inconsistent model/harnessSettings/sidecar combos can never be produced.
🧹 Nitpick comments (2)
packages/workload-router/routing-profiles/default.json (1)
17-33: ⚡ Quick winRationale text still references removed tier concepts.
The profile schema is tierless now, but many rationale strings still say “best-value/top tier/deepest tier.” Consider normalizing this wording so policy docs and runtime schema don’t contradict each other.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/workload-router/routing-profiles/default.json` around lines 17 - 33, Many rationale strings in routing-profiles/default.json still reference removed tier concepts like "best-value", "deepest tier", and "top tier"; update each affected entry (e.g., "opencode-workflow-correctness", "npm-provenance", "cloud-sandbox-infra", "sage-slack-egress-migration", "sage-proactive-rewire", "cloud-slack-proxy-guard", "sage-cloud-e2e-conduction", "capability-discovery", "npm-package-compat", "posthog", "persona-authoring", "persona-improvement", "slop-audit", "api-contract-review", "local-stack-orchestration", "e2e-validation", "write-integration-tests") to remove tier language and replace it with neutral priority guidance (for example: "prefer deeper reasoning and thorough verification", "prefer lower latency and succinct checks", or "prefer thorough verification for safety-critical changes") so the rationale strings match the new tierless schema and policy wording consistently across the file.examples/openclaw-routing.ts (1)
16-16: ⚡ Quick winUse an exhaustive harness-to-runtime mapping to avoid silent fallback behavior.
Line 16 currently sends every non-
codexharness tosubagent. If a new harness is introduced later, this can route incorrectly without a compile-time signal.Suggested refactor
- const runtime = selection.harness === 'codex' ? 'acp' : 'subagent'; + const runtime = (() => { + switch (selection.harness) { + case 'codex': + return 'acp'; + case 'claude': + case 'opencode': + return 'subagent'; + default: { + const _exhaustive: never = selection.harness; + throw new Error(`Unsupported harness: ${_exhaustive}`); + } + } + })();🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@examples/openclaw-routing.ts` at line 16, The current expression setting runtime from selection.harness (const runtime = selection.harness === 'codex' ? 'acp' : 'subagent') silently defaults every unknown harness to 'subagent'; replace it with an exhaustive harness-to-runtime mapping (e.g., a switch or a closed mapping object keyed by known harness values) and explicitly handle unknown values by throwing or logging an error so new harnesses fail fast. Update the code that reads selection.harness and assigns runtime to use that mapping (referencing selection.harness and the runtime variable) and add a clear error path for unrecognized harness names.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@examples/weekly-digest/README.md`:
- Around line 56-57: Add a short prerequisite sentence to the README near the
instructions about driving the bundle against a Relayfile mount: state that
manual firing will only produce actual GitHub writes if the Relayfile writeback
worker is running for that mount, e.g., add a note mentioning the "Relayfile
writeback worker" must be active for the mount to persist real writes from
manual triggers.
In `@packages/cli/src/local-personas.ts`:
- Around line 945-951: The assignment for systemPrompt should treat empty or
whitespace-only override values as unset like standaloneSpecFromOverride() does;
replace the nullish-coalescing line that sets systemPrompt (currently using
override.systemPrompt ?? base.systemPrompt) with logic that checks
override.systemPrompt?.trim() and uses override.systemPrompt only if that
trimmed value is non-empty, otherwise fall back to base.systemPrompt; keep the
existing behavior for harness, model, and harnessSettings (symbols: harness,
model, systemPrompt, override, base, harnessSettings,
standaloneSpecFromOverride).
In `@packages/cli/src/persona-install.ts`:
- Around line 267-271: The collision-suffix logic in the while loop using
++suffix causes the first duplicate to be named "-2" instead of "-1"; change the
increment to post-increment so the first collision yields "-1" (i.e., in the
loop that references assetKeys, assetKey, and baseKey replace the ++suffix usage
with suffix++ or otherwise adjust initialization so the first appended suffix is
1).
In `@packages/persona-kit/src/parse.test.ts`:
- Around line 107-119: The test "parsePersonaSpec throws when required runtime
fields are missing" currently supplies invalid values instead of omitting
fields; update the three assertions to pass specs that actually omit the
required keys (harness, model, systemPrompt) when calling parsePersonaSpec so
each case tests absence rather than empty/invalid values, keeping the same
expected error regexes and the same test name; locate usages of parsePersonaSpec
and validSpec in this test file to remove the harness key for the first case and
remove model and systemPrompt keys for the second and third cases respectively.
In `@packages/personas-core/personas/flake-hunter.json`:
- Line 11: Update the persona's systemPrompt string in the
personas/flake-hunter.json (the "systemPrompt" entry) to remove stale cross-tier
phrases like "top tier" and "efficient mode" and replace them with wording that
reflects the single top-level runtime config; keep the intent (brief repro
status, flake class, root cause, hardening fix, evidence) and constraints (avoid
sleeps/retries/weakened assertions/vague CI blame), but rephrase the opening to
something like a single authoritative runtime instruction (e.g., "You are a
senior flake hunter operating under the repository's top-level runtime
configuration.") so the prompt is internally consistent and concise.
In `@packages/personas-core/personas/test-strategist.json`:
- Line 10: The systemPrompt currently includes tier-relative phrasing ("senior
test strategist in efficient mode" and "top tier") which is obsolete; update the
string value assigned to systemPrompt to remove references to tiers and modes
and rephrase to a stable, non-tiered directive (e.g., "You are a senior test
strategist. Maintain high quality while reducing depth and verbosity..."),
keeping the rest of the required outputs and priorities intact; modify the
systemPrompt entry in the JSON (key: systemPrompt) to the revised one-line
prompt.
In `@packages/personas-core/scripts/validate-personas.mjs`:
- Around line 74-81: The validator currently allows legacy fields to pass; add
explicit rejection checks for persona.tiers and persona.defaultTier inside the
same validation block that checks persona fields (where persona, rel, errors and
isObject are used). If persona has a defined tiers or defaultTier property, push
a clear error message like `${rel}.tiers is deprecated` or `${rel}.defaultTier
is deprecated` (or similar) to errors so CI fails on legacy schema; keep these
checks adjacent to the existing harness/harnessSettings validations to ensure
deprecated fields are rejected early.
In `@personas/persona-improver.json`:
- Line 22: The persona JSON has inconsistent proposal count limits between the
systemPrompt phrases "Produce 0-6" and the other phrase "Identify 0–8"; make
them identical to remove nondeterminism by updating the latter to match the
former (or vice versa if you prefer a different cap), e.g., change "Identify
0–8" to "Identify 0-6" so both use the same numeric range and formatting; ensure
both occurrences in the persona-improver.json "systemPrompt" use the same range
and hyphen style and keep all other constraints unchanged.
- Line 27: The agentsMdContent still references outdated tier patch paths like
"tiers.best.systemPrompt" and instructs editing "systemPrompt per tier", which
leads to invalid proposal patch paths; update the agentsMdContent string to
remove or replace those instructions with the new patch grammar (use the literal
top-level tier keys "tiers.best", "tiers.best-value", "tiers.minimum" only as
described in the persona schema) and explicitly document the correct dot-paths
for patches (e.g., "tiers.best.systemPrompt" should be represented per the new
schema guidance or replaced with the exact approved patch path patterns),
ensuring the prose aligns with the allowed patch ops and path grammar so
generated proposals target valid JSON paths.
In `@personas/persona-maker.json`:
- Line 36: The embedded authoring spec in agentsMdContent of persona-maker.json
still requires tiered-only fields (`tiers`, `defaultTier`, tiered prompt rules)
which conflicts with the new top-level schema; update agentsMdContent so the
spec instructs authors to use top-level harness, model, systemPrompt, and
harnessSettings as the canonical shape (replace examples and language that
mandate `tiers`-only prompts), remove or reframe tier-only examples and rules,
and ensure references to prompt rules and defaults point to top-level fields
(search for the string "tiers" and symbols agentsMdContent and persona-maker in
the JSON to locate and edit the guidance).
---
Outside diff comments:
In `@packages/cli/src/cli.ts`:
- Around line 106-123: The help text for the "agent [flags] <persona>" command
is incorrect about Codex mounting; update the description to say Codex sessions
now default to the sandbox mount and that --install-in-repo opts out (i.e.,
disengages the sandbox and installs skills into the repo) to match
decideCleanMode() and tests. Edit the help string surrounding the
--install-in-repo flag in the agent help block so it references Codex using the
sandbox by default and that the flag disables that behavior.
In `@packages/workload-router/src/index.ts`:
- Around line 182-199: The function useSelection currently allows
options.harness to override only the harness field but leaves model,
harnessSettings, and sidecar from the original PersonaSelection, producing
inconsistent selections; instead, add an early guard in useSelection that if
options.harness is provided and differs from baseSelection.harness you reject it
(throw a clear error or return a failure) rather than patching the object, and
only proceed when options.harness is undefined or identical to
baseSelection.harness; keep the rest of the logic (selection creation and calls
to materializeSkillsFor and materializeSkills) unchanged but ensure the new
guard runs before constructing selection or calling
materializeSkillsFor/materializeSkills so inconsistent
model/harnessSettings/sidecar combos can never be produced.
---
Nitpick comments:
In `@examples/openclaw-routing.ts`:
- Line 16: The current expression setting runtime from selection.harness (const
runtime = selection.harness === 'codex' ? 'acp' : 'subagent') silently defaults
every unknown harness to 'subagent'; replace it with an exhaustive
harness-to-runtime mapping (e.g., a switch or a closed mapping object keyed by
known harness values) and explicitly handle unknown values by throwing or
logging an error so new harnesses fail fast. Update the code that reads
selection.harness and assigns runtime to use that mapping (referencing
selection.harness and the runtime variable) and add a clear error path for
unrecognized harness names.
In `@packages/workload-router/routing-profiles/default.json`:
- Around line 17-33: Many rationale strings in routing-profiles/default.json
still reference removed tier concepts like "best-value", "deepest tier", and
"top tier"; update each affected entry (e.g., "opencode-workflow-correctness",
"npm-provenance", "cloud-sandbox-infra", "sage-slack-egress-migration",
"sage-proactive-rewire", "cloud-slack-proxy-guard", "sage-cloud-e2e-conduction",
"capability-discovery", "npm-package-compat", "posthog", "persona-authoring",
"persona-improvement", "slop-audit", "api-contract-review",
"local-stack-orchestration", "e2e-validation", "write-integration-tests") to
remove tier language and replace it with neutral priority guidance (for example:
"prefer deeper reasoning and thorough verification", "prefer lower latency and
succinct checks", or "prefer thorough verification for safety-critical changes")
so the rationale strings match the new tierless schema and policy wording
consistently across the file.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: ad12c08d-583d-4b88-aa30-49ba96024db2
⛔ Files ignored due to path filters (1)
packages/workload-router/src/generated/personas.tsis excluded by!**/generated/**
📒 Files selected for processing (67)
examples/openclaw-routing.tsexamples/weekly-digest/README.mdexamples/weekly-digest/agent.tsexamples/weekly-digest/persona.jsonpackages/cli/src/cli.test.tspackages/cli/src/cli.tspackages/cli/src/launch-metadata.test.tspackages/cli/src/launch-metadata.tspackages/cli/src/local-personas.test.tspackages/cli/src/local-personas.tspackages/cli/src/persona-install.test.tspackages/cli/src/persona-install.tspackages/deploy/src/bundle.test.tspackages/deploy/src/deploy.test.tspackages/deploy/src/modes/sandbox.test.tspackages/persona-kit/src/constants.tspackages/persona-kit/src/execute.test.tspackages/persona-kit/src/index.test.tspackages/persona-kit/src/index.tspackages/persona-kit/src/parse.test.tspackages/persona-kit/src/parse.tspackages/persona-kit/src/plan.test.tspackages/persona-kit/src/plan.tspackages/persona-kit/src/sidecars.test.tspackages/persona-kit/src/skills.tspackages/persona-kit/src/triggers.test.tspackages/persona-kit/src/types.tspackages/personas-core/personas/architecture-planner.jsonpackages/personas-core/personas/capability-discoverer.jsonpackages/personas-core/personas/code-reviewer.jsonpackages/personas-core/personas/debugger.jsonpackages/personas-core/personas/e2e-validator.jsonpackages/personas-core/personas/flake-hunter.jsonpackages/personas-core/personas/frontend-implementer.jsonpackages/personas-core/personas/integration-test-author.jsonpackages/personas-core/personas/requirements-analyst.jsonpackages/personas-core/personas/security-reviewer.jsonpackages/personas-core/personas/tdd-guard.jsonpackages/personas-core/personas/technical-writer.jsonpackages/personas-core/personas/test-strategist.jsonpackages/personas-core/personas/verifier.jsonpackages/personas-core/scripts/validate-personas.mjspackages/runtime/src/clients/errors.tspackages/runtime/src/clients/github.test.tspackages/runtime/src/clients/github.tspackages/runtime/src/clients/index.tspackages/runtime/src/clients/jira.test.tspackages/runtime/src/clients/jira.tspackages/runtime/src/clients/linear.test.tspackages/runtime/src/clients/linear.tspackages/runtime/src/clients/notion.test.tspackages/runtime/src/clients/notion.tspackages/runtime/src/clients/request.tspackages/runtime/src/clients/slack.test.tspackages/runtime/src/clients/slack.tspackages/runtime/src/errors.tspackages/runtime/src/index.tspackages/runtime/src/runner.test.tspackages/runtime/src/types.tspackages/workload-router/routing-profiles/default.jsonpackages/workload-router/routing-profiles/schema.jsonpackages/workload-router/scripts/generate-personas.mjspackages/workload-router/src/eval.tspackages/workload-router/src/index.test.tspackages/workload-router/src/index.tspersonas/persona-improver.jsonpersonas/persona-maker.json
💤 Files with no reviewable changes (4)
- packages/persona-kit/src/constants.ts
- packages/runtime/src/clients/errors.ts
- packages/persona-kit/src/index.ts
- packages/workload-router/scripts/generate-personas.mjs
✅ Files skipped from review due to trivial changes (2)
- packages/persona-kit/src/triggers.test.ts
- packages/runtime/src/clients/jira.ts
🚧 Files skipped from review as they are similar to previous changes (12)
- packages/runtime/src/clients/notion.test.ts
- packages/runtime/src/index.ts
- packages/runtime/src/clients/notion.ts
- packages/runtime/src/clients/slack.test.ts
- examples/weekly-digest/agent.ts
- packages/runtime/src/clients/slack.ts
- packages/runtime/src/clients/linear.test.ts
- packages/runtime/src/clients/linear.ts
- packages/runtime/src/clients/index.ts
- packages/runtime/src/clients/github.test.ts
- packages/runtime/src/clients/request.ts
- packages/runtime/src/clients/github.ts
Comment on lines
+945
to
+951
| const harness = override.harness ?? base.harness; | ||
| const model = override.model ?? base.model; | ||
| const systemPrompt = override.systemPrompt ?? base.systemPrompt; | ||
| const harnessSettings: HarnessSettings = { | ||
| ...base.harnessSettings, | ||
| ...(override.harnessSettings ?? {}) | ||
| }; |
There was a problem hiding this comment.
Treat blank systemPrompt overrides as unset here.
This merge path uses ??, so an overlay with "systemPrompt": "" or whitespace replaces the inherited prompt with an empty string. That diverges from standaloneSpecFromOverride(), which trims and falls back, and it makes migrated overlays easy to break.
Suggested fix
- const systemPrompt = override.systemPrompt ?? base.systemPrompt;
+ const systemPrompt =
+ typeof override.systemPrompt === 'string' && override.systemPrompt.trim().length > 0
+ ? override.systemPrompt
+ : base.systemPrompt;📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| const harness = override.harness ?? base.harness; | |
| const model = override.model ?? base.model; | |
| const systemPrompt = override.systemPrompt ?? base.systemPrompt; | |
| const harnessSettings: HarnessSettings = { | |
| ...base.harnessSettings, | |
| ...(override.harnessSettings ?? {}) | |
| }; | |
| const harness = override.harness ?? base.harness; | |
| const model = override.model ?? base.model; | |
| const systemPrompt = | |
| typeof override.systemPrompt === 'string' && override.systemPrompt.trim().length > 0 | |
| ? override.systemPrompt | |
| : base.systemPrompt; | |
| const harnessSettings: HarnessSettings = { | |
| ...base.harnessSettings, | |
| ...(override.harnessSettings ?? {}) | |
| }; |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/cli/src/local-personas.ts` around lines 945 - 951, The assignment
for systemPrompt should treat empty or whitespace-only override values as unset
like standaloneSpecFromOverride() does; replace the nullish-coalescing line that
sets systemPrompt (currently using override.systemPrompt ?? base.systemPrompt)
with logic that checks override.systemPrompt?.trim() and uses
override.systemPrompt only if that trimmed value is non-empty, otherwise fall
back to base.systemPrompt; keep the existing behavior for harness, model, and
harnessSettings (symbols: harness, model, systemPrompt, override, base,
harnessSettings, standaloneSpecFromOverride).
Comment on lines
267
to
271
| let suffix = 1; | ||
| while (assetKeys.has(assetKey)) { | ||
| const dot = baseKey.lastIndexOf('.'); | ||
| assetKey = `${baseKey.slice(0, dot)}-${++suffix}${baseKey.slice(dot)}`; | ||
| } |
There was a problem hiding this comment.
Collision suffix starts at -2 due pre-increment.
The first duplicate asset currently becomes name-2.md instead of name-1.md. This is a small off-by-one in the collision naming loop.
🔧 Proposed fix
- let suffix = 1;
+ let suffix = 1;
while (assetKeys.has(assetKey)) {
const dot = baseKey.lastIndexOf('.');
- assetKey = `${baseKey.slice(0, dot)}-${++suffix}${baseKey.slice(dot)}`;
+ assetKey = `${baseKey.slice(0, dot)}-${suffix++}${baseKey.slice(dot)}`;
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| let suffix = 1; | |
| while (assetKeys.has(assetKey)) { | |
| const dot = baseKey.lastIndexOf('.'); | |
| assetKey = `${baseKey.slice(0, dot)}-${++suffix}${baseKey.slice(dot)}`; | |
| } | |
| let suffix = 1; | |
| while (assetKeys.has(assetKey)) { | |
| const dot = baseKey.lastIndexOf('.'); | |
| assetKey = `${baseKey.slice(0, dot)}-${suffix++}${baseKey.slice(dot)}`; | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/cli/src/persona-install.ts` around lines 267 - 271, The
collision-suffix logic in the while loop using ++suffix causes the first
duplicate to be named "-2" instead of "-1"; change the increment to
post-increment so the first collision yields "-1" (i.e., in the loop that
references assetKeys, assetKey, and baseKey replace the ++suffix usage with
suffix++ or otherwise adjust initialization so the first appended suffix is 1).
Comment on lines
+107
to
119
| test('parsePersonaSpec throws when required runtime fields are missing', () => { | ||
| assert.throws( | ||
| () => parsePersonaSpec(validSpec({ harness: 'mystery' }), 'documentation'), | ||
| /persona\[documentation\]\.harness must be one of:/ | ||
| ); | ||
| assert.throws( | ||
| () => parsePersonaSpec(validSpec({ model: '' }), 'documentation'), | ||
| /persona\[documentation\]\.model must be a non-empty string/ | ||
| ); | ||
| assert.throws( | ||
| () => parsePersonaSpec(validSpec({ systemPrompt: ' ' }), 'documentation'), | ||
| /persona\[documentation\]\.systemPrompt must be a non-empty string/ | ||
| ); |
There was a problem hiding this comment.
“Missing required fields” test is currently checking invalid values, not missing fields.
Line 109/113/117 still provide the fields, so this test does not cover actual omission and can give false confidence.
Suggested test adjustment
test('parsePersonaSpec throws when required runtime fields are missing', () => {
+ const missingHarness = validSpec();
+ delete missingHarness.harness;
assert.throws(
- () => parsePersonaSpec(validSpec({ harness: 'mystery' }), 'documentation'),
- /persona\[documentation\]\.harness must be one of:/
+ () => parsePersonaSpec(missingHarness, 'documentation'),
+ /persona\[documentation\]\.harness/
);
+ const missingModel = validSpec();
+ delete missingModel.model;
assert.throws(
- () => parsePersonaSpec(validSpec({ model: '' }), 'documentation'),
- /persona\[documentation\]\.model must be a non-empty string/
+ () => parsePersonaSpec(missingModel, 'documentation'),
+ /persona\[documentation\]\.model/
);
+ const missingSystemPrompt = validSpec();
+ delete missingSystemPrompt.systemPrompt;
assert.throws(
- () => parsePersonaSpec(validSpec({ systemPrompt: ' ' }), 'documentation'),
- /persona\[documentation\]\.systemPrompt must be a non-empty string/
+ () => parsePersonaSpec(missingSystemPrompt, 'documentation'),
+ /persona\[documentation\]\.systemPrompt/
);
});🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/persona-kit/src/parse.test.ts` around lines 107 - 119, The test
"parsePersonaSpec throws when required runtime fields are missing" currently
supplies invalid values instead of omitting fields; update the three assertions
to pass specs that actually omit the required keys (harness, model,
systemPrompt) when calling parsePersonaSpec so each case tests absence rather
than empty/invalid values, keeping the same expected error regexes and the same
test name; locate usages of parsePersonaSpec and validSpec in this test file to
remove the harness key for the first case and remove model and systemPrompt keys
for the second and third cases respectively.
| } | ||
| "harness": "opencode", | ||
| "model": "opencode/gpt-5-nano", | ||
| "systemPrompt": "You are a senior flake hunter in efficient mode. Keep the same quality bar as top tier; reduce only depth and verbosity. Reproduce the flake, isolate the unstable path, classify the failure mode, fix the root cause, and provide repeat-run evidence. Priorities remain reproducibility, root-cause correctness, and preserving test signal. Avoid arbitrary sleeps, blind retries, weakened assertions, and vague CI blame. Output contract: brief repro status, flake class, root cause, hardening fix, and evidence.", |
There was a problem hiding this comment.
Remove stale cross-tier wording from systemPrompt.
Line 11 still references “top tier” and “efficient mode,” but this persona now has a single top-level runtime config. That wording is internally inconsistent and weakens instruction clarity.
Suggested edit
- "systemPrompt": "You are a senior flake hunter in efficient mode. Keep the same quality bar as top tier; reduce only depth and verbosity. Reproduce the flake, isolate the unstable path, classify the failure mode, fix the root cause, and provide repeat-run evidence. Priorities remain reproducibility, root-cause correctness, and preserving test signal. Avoid arbitrary sleeps, blind retries, weakened assertions, and vague CI blame. Output contract: brief repro status, flake class, root cause, hardening fix, and evidence.",
+ "systemPrompt": "You are a senior flake hunter. Reproduce the flake, isolate the unstable path, classify the failure mode, fix the root cause, and provide repeat-run evidence. Priorities: reproducibility, root-cause correctness, and preserving test signal. Avoid arbitrary sleeps, blind retries, weakened assertions, and vague CI blame. Output contract: brief repro status, flake class, root cause, hardening fix, and evidence.",🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/personas-core/personas/flake-hunter.json` at line 11, Update the
persona's systemPrompt string in the personas/flake-hunter.json (the
"systemPrompt" entry) to remove stale cross-tier phrases like "top tier" and
"efficient mode" and replace them with wording that reflects the single
top-level runtime config; keep the intent (brief repro status, flake class, root
cause, hardening fix, evidence) and constraints (avoid sleeps/retries/weakened
assertions/vague CI blame), but rephrase the opening to something like a single
authoritative runtime instruction (e.g., "You are a senior flake hunter
operating under the repository's top-level runtime configuration.") so the
prompt is internally consistent and concise.
| } | ||
| "harness": "opencode", | ||
| "model": "opencode/gpt-5-nano", | ||
| "systemPrompt": "You are a senior test strategist in efficient mode. Keep the same quality bar as top tier; reduce only depth and verbosity. Inspect the changed behavior, rank the biggest risks, recommend the smallest useful unit/integration/e2e coverage set, and label gaps as Critical, Important, or Nice-to-have. Priorities remain: regression prevention, contract safety, reliability, and fit with existing test patterns. Avoid noisy blanket coverage requests, implementation-detail coupling, and unnecessary end-to-end expansion. Output contract: brief test plan, risk-ranked gaps, recommended layer per behavior, and explicit deferrals.", |
There was a problem hiding this comment.
Drop tier-relative phrasing from systemPrompt.
Line 10 references “top tier” and “efficient mode,” but this persona no longer has tiered runtime settings. Keeping this phrasing makes the prompt self-contradictory.
Suggested edit
- "systemPrompt": "You are a senior test strategist in efficient mode. Keep the same quality bar as top tier; reduce only depth and verbosity. Inspect the changed behavior, rank the biggest risks, recommend the smallest useful unit/integration/e2e coverage set, and label gaps as Critical, Important, or Nice-to-have. Priorities remain: regression prevention, contract safety, reliability, and fit with existing test patterns. Avoid noisy blanket coverage requests, implementation-detail coupling, and unnecessary end-to-end expansion. Output contract: brief test plan, risk-ranked gaps, recommended layer per behavior, and explicit deferrals.",
+ "systemPrompt": "You are a senior test strategist. Inspect the changed behavior, rank the biggest risks, recommend the smallest useful unit/integration/e2e coverage set, and label gaps as Critical, Important, or Nice-to-have. Priorities: regression prevention, contract safety, reliability, and fit with existing test patterns. Avoid noisy blanket coverage requests, implementation-detail coupling, and unnecessary end-to-end expansion. Output contract: brief test plan, risk-ranked gaps, recommended layer per behavior, and explicit deferrals.",📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| "systemPrompt": "You are a senior test strategist in efficient mode. Keep the same quality bar as top tier; reduce only depth and verbosity. Inspect the changed behavior, rank the biggest risks, recommend the smallest useful unit/integration/e2e coverage set, and label gaps as Critical, Important, or Nice-to-have. Priorities remain: regression prevention, contract safety, reliability, and fit with existing test patterns. Avoid noisy blanket coverage requests, implementation-detail coupling, and unnecessary end-to-end expansion. Output contract: brief test plan, risk-ranked gaps, recommended layer per behavior, and explicit deferrals.", | |
| "systemPrompt": "You are a senior test strategist. Inspect the changed behavior, rank the biggest risks, recommend the smallest useful unit/integration/e2e coverage set, and label gaps as Critical, Important, or Nice-to-have. Priorities: regression prevention, contract safety, reliability, and fit with existing test patterns. Avoid noisy blanket coverage requests, implementation-detail coupling, and unnecessary end-to-end expansion. Output contract: brief test plan, risk-ranked gaps, recommended layer per behavior, and explicit deferrals.", |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/personas-core/personas/test-strategist.json` at line 10, The
systemPrompt currently includes tier-relative phrasing ("senior test strategist
in efficient mode" and "top tier") which is obsolete; update the string value
assigned to systemPrompt to remove references to tiers and modes and rephrase to
a stable, non-tiered directive (e.g., "You are a senior test strategist.
Maintain high quality while reducing depth and verbosity..."), keeping the rest
of the required outputs and priorities intact; modify the systemPrompt entry in
the JSON (key: systemPrompt) to the revised one-line prompt.
Comment on lines
+74
to
+81
| for (const field of ['harness', 'model', 'systemPrompt']) { | ||
| if (typeof persona[field] !== 'string' || persona[field].trim() === '') { | ||
| errors.push(`${rel}.${field} must be a non-empty string`); | ||
| } | ||
| } | ||
| if (!isObject(persona.harnessSettings)) { | ||
| errors.push(`${rel}.harnessSettings must be an object`); | ||
| } |
There was a problem hiding this comment.
Validator should explicitly reject deprecated tier fields.
The migration is to top-level runtime fields, but the validator still allows tiers / defaultTier to remain silently. Add explicit rejection so legacy schema cannot pass CI.
Suggested patch
for (const field of ['harness', 'model', 'systemPrompt']) {
if (typeof persona[field] !== 'string' || persona[field].trim() === '') {
errors.push(`${rel}.${field} must be a non-empty string`);
}
}
if (!isObject(persona.harnessSettings)) {
errors.push(`${rel}.harnessSettings must be an object`);
}
+ if (persona.tiers !== undefined) {
+ errors.push(`${rel}.tiers is deprecated; use top-level harness/model/systemPrompt/harnessSettings`);
+ }
+ if (persona.defaultTier !== undefined) {
+ errors.push(`${rel}.defaultTier is deprecated and must be removed`);
+ }📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| for (const field of ['harness', 'model', 'systemPrompt']) { | |
| if (typeof persona[field] !== 'string' || persona[field].trim() === '') { | |
| errors.push(`${rel}.${field} must be a non-empty string`); | |
| } | |
| } | |
| if (!isObject(persona.harnessSettings)) { | |
| errors.push(`${rel}.harnessSettings must be an object`); | |
| } | |
| for (const field of ['harness', 'model', 'systemPrompt']) { | |
| if (typeof persona[field] !== 'string' || persona[field].trim() === '') { | |
| errors.push(`${rel}.${field} must be a non-empty string`); | |
| } | |
| } | |
| if (!isObject(persona.harnessSettings)) { | |
| errors.push(`${rel}.harnessSettings must be an object`); | |
| } | |
| if (persona.tiers !== undefined) { | |
| errors.push(`${rel}.tiers is deprecated; use top-level harness/model/systemPrompt/harnessSettings`); | |
| } | |
| if (persona.defaultTier !== undefined) { | |
| errors.push(`${rel}.defaultTier is deprecated and must be removed`); | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/personas-core/scripts/validate-personas.mjs` around lines 74 - 81,
The validator currently allows legacy fields to pass; add explicit rejection
checks for persona.tiers and persona.defaultTier inside the same validation
block that checks persona fields (where persona, rel, errors and isObject are
used). If persona has a defined tiers or defaultTier property, push a clear
error message like `${rel}.tiers is deprecated` or `${rel}.defaultTier is
deprecated` (or similar) to errors so CI fails on legacy schema; keep these
checks adjacent to the existing harness/harnessSettings validations to ensure
deprecated fields are rejected early.
| } | ||
| "harness": "opencode", | ||
| "model": "opencode/gpt-5-nano", | ||
| "systemPrompt": "You are a persona-improvement engineer. Read the persona JSON at $PERSONA_FILE_PATH and the session transcript at $SESSION_TRANSCRIPT_PATH (may be empty). Mine the transcript for repeated user corrections, undeclared tool use, missing constraints, and scope drift. Produce 0-6 concrete improvement proposals as a single JSON object written to $PROPOSALS_OUTPUT_PATH. Use the patch schema and anti-goals defined in AGENTS.md. Each proposal must be high-leverage; zero proposals is a valid outcome. Do not modify the persona JSON. Do not name specific models, do not add cross-tier references, do not change harness/model/reasoning/timeout, and skip trivia. Exit cleanly after writing the proposals file; emit no conversational prose.", |
There was a problem hiding this comment.
Proposal count contract is inconsistent (0-6 vs 0-8).
Line 22 says “Produce 0-6,” while Line 27 says “Identify 0–8.” Keep one limit to avoid nondeterministic output behavior.
Also applies to: 27-27
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@personas/persona-improver.json` at line 22, The persona JSON has inconsistent
proposal count limits between the systemPrompt phrases "Produce 0-6" and the
other phrase "Identify 0–8"; make them identical to remove nondeterminism by
updating the latter to match the former (or vice versa if you prefer a different
cap), e.g., change "Identify 0–8" to "Identify 0-6" so both use the same numeric
range and formatting; ensure both occurrences in the persona-improver.json
"systemPrompt" use the same range and hyphen style and keep all other
constraints unchanged.
| "reasoning": "medium", | ||
| "timeoutSeconds": 600 | ||
| }, | ||
| "agentsMdContent": "# Persona improver — AgentWorkforce `workforce` repo\n\nYou improve an existing local persona JSON file by mining one finished session for concrete, actionable changes. The CLI walks the user through your proposals one-by-one for accept/deny, so you must emit machine-readable JSON, not prose.\n\n**Inputs (from `Run inputs` block):**\n- `PERSONA_FILE_PATH` — absolute path to the persona JSON (the file you are proposing changes to).\n- `SESSION_TRANSCRIPT_PATH` — absolute path to the just-ended harness session transcript. May be empty.\n- `PROPOSALS_OUTPUT_PATH` — absolute path to write your proposals JSON.\n\n**Process:**\n1. Read the persona JSON at `PERSONA_FILE_PATH`. Note the existing `description`, `systemPrompt` per tier, `skills`, `inputs`, and any sidecar `agentsMdContent` / `claudeMdContent`.\n2. Read the session transcript at `SESSION_TRANSCRIPT_PATH` if provided. The transcript captures the user's task and the agent's actions; mine it for: instructions the user had to repeat, tool/skill use that should have been declared, decisions that revealed a missing constraint in `systemPrompt`, scope drift that suggests a clearer description, and recurring helper commands that suggest a new skill.\n3. Identify 0–8 high-leverage proposed improvements. Quality over quantity: zero proposals is a valid outcome. Skip noise (whitespace, trivial wording, model bumps).\n4. Write the proposals to `PROPOSALS_OUTPUT_PATH` per the schema below. The file must be valid JSON and parseable on first read.\n5. Exit cleanly. Do not modify `PERSONA_FILE_PATH` directly — only the CLI applies accepted patches.\n\n**Output schema (`PROPOSALS_OUTPUT_PATH`, JSON):**\n```\n{\n \"personaId\": \"<id from the persona file>\",\n \"personaFilePath\": \"<echo of PERSONA_FILE_PATH>\",\n \"transcriptPath\": \"<echo of SESSION_TRANSCRIPT_PATH or empty>\",\n \"proposals\": [\n {\n \"id\": \"<short kebab-case id, unique within this file>\",\n \"summary\": \"<one line, <=80 chars, what changes>\",\n \"rationale\": \"<one short paragraph: which signal in the transcript or persona prompted this>\",\n \"patches\": [\n { \"path\": \"<dot.path.into.persona.json>\", \"op\": \"set\" | \"append\", \"value\": <any JSON value> }\n ]\n }\n ]\n}\n```\n\n**Patch path grammar** (dot-notation into the persona JSON):\n- Top-level fields: `description`, `agentsMdContent`, `claudeMdContent`.\n- Tier runtime: `tiers.best.systemPrompt`, `tiers.best-value.systemPrompt`, `tiers.minimum.systemPrompt`. Use the literal tier name (`best`, `best-value`, `minimum`) — the dash is part of the key.\n- Skill add: `skills` with `op: \"append\"` and a value of `{\"id\": \"...\", \"source\": \"...\", \"description\": \"...\"}`.\n- Inputs add: `inputs.<NAME>` with `op: \"set\"` and a value of `{\"description\": \"...\", \"default\": \"...\"}` or `{\"description\": \"...\"}`.\n- Tags replace: `tags` with `op: \"set\"` and a string array.\n\n**Patch ops:**\n- `set`: replace the value at the dot path. Creates intermediate objects if missing.\n- `append`: array push; only valid when the target resolves to an array.\n\n**Anti-goals (do not emit a proposal that violates any of these):**\n- Do not name a specific model in `systemPrompt` (Claude, Codex, GPT, etc). Persona prompts are model-agnostic.\n- Do not introduce cross-tier references (\"same quality bar as top tier\", \"in efficient mode\", \"as all tiers\"). Each tier prompt stands alone.\n- Do not propose changes to `harness`, `model`, `harnessSettings.reasoning`, or `harnessSettings.timeoutSeconds`. Tier wiring is the user's choice, not yours.\n- Do not propose changes to `id` or `intent`. Identity is fixed.\n- Do not add a skill that is just a one-flag CLI wrapper. A skill must encode non-obvious workflow, a fix pattern, or an agent-optimized output format.\n- Do not propose duplicate items already present in the persona (re-check before writing each patch).\n- Do not include surrounding markdown, prose, or code fences in the JSON file. Pure JSON only.\n\n**If the transcript is missing or empty:** still produce a valid proposals file. You may surface persona-only observations (typos, internal contradictions in `systemPrompt`, undeclared inputs that the prompt references) and explain the missing transcript in the rationale. If you find nothing actionable, write `{\"personaId\": \"...\", \"personaFilePath\": \"...\", \"transcriptPath\": \"\", \"proposals\": []}` and exit.\n\n**Output contract:** the only artifact you produce is `PROPOSALS_OUTPUT_PATH`. Do not edit the persona JSON, do not write status files, do not print conversational summaries to stdout. The CLI will read your JSON and present each proposal to the user.\n" |
There was a problem hiding this comment.
agentsMdContent still teaches deprecated tier patch paths.
Line 27 still instructs edits like tiers.best.systemPrompt and “systemPrompt per tier,” which conflicts with the new top-level persona schema. This can produce invalid proposals or patches targeting dead paths.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@personas/persona-improver.json` at line 27, The agentsMdContent still
references outdated tier patch paths like "tiers.best.systemPrompt" and
instructs editing "systemPrompt per tier", which leads to invalid proposal patch
paths; update the agentsMdContent string to remove or replace those instructions
with the new patch grammar (use the literal top-level tier keys "tiers.best",
"tiers.best-value", "tiers.minimum" only as described in the persona schema) and
explicitly document the correct dot-paths for patches (e.g.,
"tiers.best.systemPrompt" should be represented per the new schema guidance or
replaced with the exact approved patch path patterns), ensuring the prose aligns
with the allowed patch ops and path grammar so generated proposals target valid
JSON paths.
khaliqgant
added a commit
that referenced
this pull request
May 12, 2026
Aligns the MCP server with the runtime's new client shape from #92. Before: the integration tools called createGithubClient({ token }) using WORKFORCE_INTEGRATION_GITHUB_TOKEN. That signature no longer exists in the runtime now that github speaks Relayfile-VFS, so the MCP package would fail to compile once #92 lands. Config (config.ts) - WorkforceMcpConfig drops `providerTokens`. The MCP server is no longer the place to hold provider PATs — Relayfile holds the credentials and the writeback worker uses them. - New `relayfileMountRoot` field, populated from RELAYFILE_MOUNT_ROOT (with RELAYFILE_ROOT as a legacy alias). The workforce runtime sets these env vars automatically when it spawns the harness via ctx.harness.run. - New `writebackTimeoutMs` field (default 30s, overridable via WORKFORCE_WRITEBACK_TIMEOUT_MS). Passed straight through to integration clients so handlers that need a synchronous receipt pay the same wait the runtime would. Integration dispatcher (tools/integrations.ts) - resolveGithub() now constructs createGithubClient with { relayfileMountRoot, writebackTimeoutMs } from config instead of a token. Refuses to construct when the mount root is missing with a message pointing at the runtime contract. Tests - config.test exercises RELAYFILE_MOUNT_ROOT (+ RELAYFILE_ROOT alias) and WORKFORCE_WRITEBACK_TIMEOUT_MS overrides. - integrations.test now writes against a tempdir mount and reads the resulting draft JSON file back to assert the canonical shape Relayfile expects. Covers happy path, missing-mount-root failure, postReview enum validation, and field-pointed errors. - server.test loads config with RELAYFILE_MOUNT_ROOT instead of a github PAT. - workflow.test + memory.test drop the obsolete providerTokens fixture key. 23 mcp-workforce tests pass (up from 21). PR base flips from main to feat/integrations-vfs (PR #92) since the new client shape lives there. Auto-rebases to main when #92 merges. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
khaliqgant
added a commit
that referenced
this pull request
May 12, 2026
Ports the two example agents from the closed codex/deploy-v1-pr branch to the Relayfile-VFS integration-client style introduced in #92. review-agent - GitHub PR opened: pulls the diff via ctx.github.getPr, runs the persona's harness on the diff body, posts a review via ctx.github.postReview. - @mention in an issue/review comment: harness with the comment thread as context, posts the reply via ctx.github.comment. - check_run.completed (failure): harness with the failed CI logs as context, proposes a fix in a comment. - Slack app_mention: conversational reply via ctx.slack. linear-shipper - Linear issue created: clones the target repo into the sandbox, runs ctx.harness.run on the issue body, opens a draft PR via ctx.github, comments back on the Linear issue with the PR link. - Headless (no traits in the persona); demonstrates the paraglide "Linear issue → ship" pattern. Both examples adapt to the WorkforceProviderEvent shape — they read the raw provider payload from event.payload rather than treating the event as the payload itself. Tests: typecheck clean across the workspace and against examples/tsconfig.json (which path-maps @agentworkforce/runtime to the workspace source). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
khaliqgant
force-pushed
the
feat/integrations-vfs
branch
2 times, most recently
from
1225e04 to
af8f4a2
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (3)
examples/weekly-digest/README.md (2)
56-57:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd explicit prerequisite that the Relayfile writeback worker must be running.
The manual trigger section should call out that real GitHub writes only occur when the writeback worker is active for that mount.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@examples/weekly-digest/README.md` around lines 56 - 57, Add an explicit prerequisite to the "manual trigger" section of the README stating that the Relayfile writeback worker must be running for real GitHub writes to occur; mention the Relayfile mount used by the example and call out that without the writeback worker active, the bundle will not perform actual GitHub write operations (only local or simulated changes).
60-62:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winScope
RELAYFILE_MOUNT_ROOTto thenodeprocess, notecho.In this pipeline form, the env assignment applies to
echo, sorunner.mjsmay not seeRELAYFILE_MOUNT_ROOT.Suggested fix
-RELAYFILE_MOUNT_ROOT=/path/to/mount \ -echo '{"id":"manual-1","workspace":"ws_demo","type":"cron.tick","occurredAt":"2026-05-12T09:00:00Z","name":"weekly","cron":"0 9 * * 6"}' \ - | node /tmp/wf-weekly-digest/runner.mjs +echo '{"id":"manual-1","workspace":"ws_demo","type":"cron.tick","occurredAt":"2026-05-12T09:00:00Z","name":"weekly","cron":"0 9 * * 6"}' \ + | RELAYFILE_MOUNT_ROOT=/path/to/mount node /tmp/wf-weekly-digest/runner.mjs#!/bin/bash set -euo pipefail RELAYFILE_MOUNT_ROOT=/tmp/demo printf 'x\n' | /usr/bin/env | rg -n 'RELAYFILE_MOUNT_ROOT' || true printf 'x\n' | RELAYFILE_MOUNT_ROOT=/tmp/demo /usr/bin/env | rg -n 'RELAYFILE_MOUNT_ROOT'🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@examples/weekly-digest/README.md` around lines 60 - 62, The environment variable RELAYFILE_MOUNT_ROOT is currently placed before echo so it only applies to echo; move the RELAYFILE_MOUNT_ROOT assignment to the node process invocation so runner.mjs receives it (e.g., prefix the node /tmp/wf-weekly-digest/runner.mjs invocation with RELAYFILE_MOUNT_ROOT=... while keeping the piped JSON from echo), ensuring RELAYFILE_MOUNT_ROOT is exported to the process that runs runner.mjs and not just to echo.packages/runtime/src/clients/request.ts (1)
225-239:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAvoid parsing the draft payload in fire-and-forget mode before timeout gating.
waitForReceiptcurrently parses once before checkingtimeoutMs <= 0, so payloads that containid/path/createdcan be misread as a receipt.Suggested minimal fix
async function waitForReceipt( absolutePath: string, client: IntegrationClientOptions ): Promise<WritebackReceipt | undefined> { const timeoutMs = client.writebackTimeoutMs ?? 0; + if (timeoutMs <= 0) return undefined; const deadline = Date.now() + timeoutMs; do { const parsed = await readCurrentJson(absolutePath); @@ ) { return parsed as WritebackReceipt; } - if (timeoutMs <= 0) return undefined; await new Promise((resolve) => setTimeout(resolve, client.writebackPollMs ?? 250)); } while (Date.now() < deadline); return undefined; }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/runtime/src/clients/request.ts` around lines 225 - 239, waitForReceipt currently reads and parses the draft file before checking whether writebackTimeoutMs is non-positive, causing fire-and-forget calls to accidentally interpret draft payloads as receipts; fix by gating the read/parse with the timeout check—check if timeoutMs <= 0 and return undefined before calling readCurrentJson(absolutePath), or perform that check at loop start (using timeoutMs and deadline) so readCurrentJson and the isRecord/id|path|created checks only run when polling is enabled; update the function waitForReceipt and its use of timeoutMs/client.writebackPollMs accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/plans/deploy-v1-schema-cascade-spec.md`:
- Around line 47-1362: The review flags unlabeled fenced code blocks (MD040) in
docs/plans/deploy-v1-schema-cascade-spec.md; add explicit language identifiers
to each triple-backtick fence (e.g. ```bash for shell snippets like the
HOME/ROOT block and gh commands, ```ts for TypeScript examples, ```json for JSON
bodies such as persona/bundle schemas, and ```text where generic text is
intended) so markdownlint passes. Locate every fenced block in the file
(examples: the initial HOME/ROOT block, PersonaSpec snippets, gh CLI snippets,
and JSON API contract examples) and update the opening fence to include the
appropriate language token, keeping the fence contents unchanged.
---
Duplicate comments:
In `@examples/weekly-digest/README.md`:
- Around line 56-57: Add an explicit prerequisite to the "manual trigger"
section of the README stating that the Relayfile writeback worker must be
running for real GitHub writes to occur; mention the Relayfile mount used by the
example and call out that without the writeback worker active, the bundle will
not perform actual GitHub write operations (only local or simulated changes).
- Around line 60-62: The environment variable RELAYFILE_MOUNT_ROOT is currently
placed before echo so it only applies to echo; move the RELAYFILE_MOUNT_ROOT
assignment to the node process invocation so runner.mjs receives it (e.g.,
prefix the node /tmp/wf-weekly-digest/runner.mjs invocation with
RELAYFILE_MOUNT_ROOT=... while keeping the piped JSON from echo), ensuring
RELAYFILE_MOUNT_ROOT is exported to the process that runs runner.mjs and not
just to echo.
In `@packages/runtime/src/clients/request.ts`:
- Around line 225-239: waitForReceipt currently reads and parses the draft file
before checking whether writebackTimeoutMs is non-positive, causing
fire-and-forget calls to accidentally interpret draft payloads as receipts; fix
by gating the read/parse with the timeout check—check if timeoutMs <= 0 and
return undefined before calling readCurrentJson(absolutePath), or perform that
check at loop start (using timeoutMs and deadline) so readCurrentJson and the
isRecord/id|path|created checks only run when polling is enabled; update the
function waitForReceipt and its use of timeoutMs/client.writebackPollMs
accordingly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: f56b1240-7b01-4783-a3b2-bb8f5b17282f
⛔ Files ignored due to path filters (1)
workflows/generated/ricky-ricky-workflow-spec-deploy-v1-schema-cascade-persona-refactor-status-ready-for-r.tsis excluded by!**/generated/**
📒 Files selected for processing (19)
docs/plans/deploy-v1-schema-cascade-spec.mdexamples/weekly-digest/README.mdexamples/weekly-digest/agent.tspackages/runtime/src/clients/errors.tspackages/runtime/src/clients/github.test.tspackages/runtime/src/clients/github.tspackages/runtime/src/clients/index.tspackages/runtime/src/clients/jira.test.tspackages/runtime/src/clients/jira.tspackages/runtime/src/clients/linear.test.tspackages/runtime/src/clients/linear.tspackages/runtime/src/clients/notion.test.tspackages/runtime/src/clients/notion.tspackages/runtime/src/clients/request.tspackages/runtime/src/clients/slack.test.tspackages/runtime/src/clients/slack.tspackages/runtime/src/errors.tspackages/runtime/src/index.tspackages/runtime/src/types.ts
💤 Files with no reviewable changes (1)
- packages/runtime/src/clients/errors.ts
🚧 Files skipped from review as they are similar to previous changes (14)
- packages/runtime/src/clients/notion.test.ts
- packages/runtime/src/index.ts
- examples/weekly-digest/agent.ts
- packages/runtime/src/clients/linear.ts
- packages/runtime/src/clients/jira.test.ts
- packages/runtime/src/clients/jira.ts
- packages/runtime/src/errors.ts
- packages/runtime/src/clients/linear.test.ts
- packages/runtime/src/clients/slack.test.ts
- packages/runtime/src/clients/notion.ts
- packages/runtime/src/clients/github.test.ts
- packages/runtime/src/clients/index.ts
- packages/runtime/src/clients/slack.ts
- packages/runtime/src/clients/github.ts
Comment on lines
+47
to
+1362
| ``` | ||
| HOME=/Users/khaliqgant | ||
| ROOT=$HOME/Projects/AgentWorkforce | ||
|
|
||
| CLOUD_REPO=$ROOT/cloud | ||
| WORKFORCE_REPO=$ROOT/workforce | ||
| RELAY_REPO=$ROOT/relay # read-only — verify relay#844 merge state | ||
| ``` | ||
|
|
||
| ### Required secrets | ||
|
|
||
| ``` | ||
| GITHUB_TOKEN | ||
| ``` | ||
|
|
||
| ### Coordination | ||
|
|
||
| Hub-spoke. Lead Claude Opus stays on `#wf-schema-cascade` as architect + ambient reviewer. | ||
|
|
||
| ### Never-fail mechanics (mirror `proactive-runtime-m1.ts`) | ||
|
|
||
| - Every test / typecheck / regression gate runs as **soft → fixer → hard**. | ||
| - Two review rounds: peer review → signoff → router → fix-r2 → final signoff. If round 2 still has gaps, the PR opens as DRAFT with the gap list in the body. Workflow exits 0. | ||
| - Global `onError`: retry 2× with 10s backoff. | ||
| - Per-track self-reflection vs that track's section below. | ||
|
|
||
| ### Worktree layout | ||
|
|
||
| ``` | ||
| $CLOUD_REPO # Track A (issue body + migrations PR) — operates in place | ||
| $CLOUD_REPO.wt-resolver # Track B | ||
| $WORKFORCE_REPO # Track D (persona-kit refactor — owns primary checkout) | ||
| $WORKFORCE_REPO.wt-runtime # Track F (runtime input-values resolution) | ||
| $WORKFORCE_REPO.wt-rebase-92 # Track E sub-tracks (one worktree per workforce PR) | ||
| $WORKFORCE_REPO.wt-rebase-93 | ||
| $WORKFORCE_REPO.wt-rebase-94 | ||
| $WORKFORCE_REPO.wt-rebase-96 | ||
| $WORKFORCE_REPO.wt-rebase-97 | ||
| ``` | ||
|
|
||
| Create with `git worktree add <path> -b <branch> <base>`. Cleanup: never run `git worktree remove`. Leave worktrees in place for human inspection. | ||
|
|
||
| ### PR conventions | ||
|
|
||
| - **PRs open as DRAFT initially. Workflow auto-flips to ready + AUTO-MERGES** when all gates pass (see Auto-merge directive below). Khaliq has explicitly authorized auto-merge for this workflow so when he wakes up everything is wired and ready to test. | ||
| - Title format: `<type>(<scope>): <summary>`. | ||
| - Body references this spec file path (`workforce/docs/plans/deploy-v1-schema-cascade-spec.md`) and a per-track acceptance checklist (checked/unchecked). | ||
| - Commit trailer: `Co-Authored-By: <implementer model> via Ricky <noreply@agentworkforce.com>`. | ||
| - No `--no-verify`. Fix hook failures and create a new commit. | ||
|
|
||
| ### Auto-merge directive (FLIP from prior DRAFT-only posture) | ||
|
|
||
| After each track's PR is opened, the workflow's lead Claude: | ||
|
|
||
| 1. **Waits for CI green** on the PR (all required checks passing, no failures, no in-progress). | ||
| 2. **Runs the soft → fixer → hard gate loop** until tests + typecheck are clean. | ||
| 3. **Verifies all upstream dependencies are merged** (per the Merge DAG below). | ||
| 4. **Verifies no merge conflicts** with target base branch. | ||
| 5. **Verifies no human review has requested changes** (`gh pr view --json reviews` returns no `CHANGES_REQUESTED` from a non-bot reviewer). | ||
| 6. **Flips PR from draft to ready** (`gh pr ready <num>`). | ||
| 7. **Merges via squash** (`gh pr merge <num> --squash --auto`) — uses `--auto` so if CI is still settling, GitHub merges as soon as it goes green. | ||
| 8. **Posts a status line into `#wf-schema-cascade`**: "merged: <PR> (#X)". | ||
|
|
||
| **Gates that BLOCK auto-merge** (workflow stops cascade, posts loud alert): | ||
| - Any required CI check returns FAILURE after the fixer loop. | ||
| - Any human reviewer left `CHANGES_REQUESTED` (don't override). | ||
| - **Any unresolved review comment thread** from a human reviewer — query `gh api repos/<owner>/<repo>/pulls/<n>/comments` and skip auto-merge if any thread has `in_reply_to_id` chains where the last reply is from a non-bot reviewer and the thread isn't marked resolved. ("As long as there are no outstanding review comments" — Khaliq, May 12.) | ||
| - Merge conflict that fixer can't resolve. | ||
| - A downstream-track PR was already opened and its CI breaks post-merge of an upstream track → STOP, do not merge further. | ||
|
|
||
| **Cross-repo merge ordering:** the workflow walks the Merge DAG (below) topologically. Within a single repo, tracks merge sequentially. Across repos, paired-contract PRs (cloud#548 + relaycron#5) merge as a pair via short polling: workflow merges cloud#548 first, then immediately verifies relaycron#5 still green + merges it; if relaycron#5 breaks in between, the workflow flags it but doesn't roll back cloud#548 (Khaliq handles). | ||
|
|
||
| **What the workflow will NOT auto-merge:** | ||
| - workforce#89 (README rewrite — DRAFT by design, docs polish, not blocking). | ||
| - workforce#87 (proactive-agent-builder persona) — auto-merge IF #87 still has the `parseInputsShape` `optional: true` regression fix, since Track F's input resolution depends on it. Otherwise skip. | ||
| - cloud#554 (Daytona meter) — platform-team gates on meter name + autostop reconciliation; flag for Khaliq's morning review, don't merge. | ||
| - Anything in the "Out of scope" list. | ||
|
|
||
| **Rollback policy:** the workflow doesn't auto-revert. If a merge breaks a downstream track, the workflow stops, posts the broken state, and leaves all repos in their merged-so-far state for Khaliq to inspect. This is intentional: incomplete cascade is recoverable; rolling back partial cross-repo merges is not. | ||
|
|
||
| --- | ||
|
|
||
| ## Out of scope (DO NOT implement) | ||
|
|
||
| The following decisions were explicitly punted in the May 12 meetings. **Ricky must NOT enact any of these.** If an implementer agent proposes changes in these areas, fail the soft-gate. | ||
|
|
||
| 1. **Multi-persona collaboration team table.** `agent_teams` or similar grouping table is NOT in v1. RelayCast workspace IS the de facto grouping; the only multi-agent observability is the `spawned_by_agent_id` back-pointer in Track A. | ||
| 2. **Persona-spec timeout fields.** Timeouts are runtime-managed for v1 with sensible defaults per `trigger_kind`. Don't add `timeout_seconds` to `PersonaSpec`. | ||
| 3. **`workforce deployments destroy/list` CLI commands.** M3 milestone — separate workflow file. | ||
| 4. **Persona-personality-builder tool.** Future package; not part of persona-kit v1. | ||
| 5. **Trait → expression auto-mapping** in the proactive bridge. Traits removed entirely from persona spec (Track D); no replacement in v1. | ||
| 6. **LLM-judge timeout resumption logic.** Khaliq mentioned as "an option for later" — runtime layer, not schema. | ||
| 7. **`@workforce/daytona-runner` npm publish.** A separate agent is handling publishing under the `@workforce` OIDC trusted-publisher scope. Do NOT touch the daytona-runner package or its workspace ref in this workflow. | ||
|
|
||
| ### Loud hole: memory wiring (intentionally out of scope, intentionally loud) | ||
|
|
||
| Memory is NOT wired end-to-end after this workflow completes. The schema has the supermemory pointer in External state, and `PersonaSpec.memory` declares `scopes` + `ttlDays`, but **the runtime does not inject the supermemory API key, does not call save/recall, and `ctx.memory` returns a stub.** | ||
|
|
||
| This is a deliberate hole. Memory architecture is being worked through separately. After this workflow lands: | ||
|
|
||
| - `ctx.memory.save(...)` will type-check and compile, but at runtime it will log a warning and no-op. | ||
| - `ctx.memory.recall(...)` returns `[]`. | ||
| - A deployed agent that calls memory APIs runs cleanly but has no persistence. | ||
|
|
||
| **When memory IS wired** (separate follow-up spec), the locked decisions from the May 12 diagrams are: | ||
|
|
||
| - `enabled: bool` | ||
| - `scopes: 'workspace' | 'user' | 'global'` (per image 1 of the whimsical diagram — note: **no `session` scope, and a `global` scope is added** vs the old deploy-v1.md prose). | ||
| - `ttl: number` | ||
|
|
||
| Track D's persona-kit refactor MUST keep `PersonaSpec.memory.scopes` accepting `'workspace' | 'user' | 'global'` (drop `session` from the accepted union if it's there from pre-flatten code). | ||
|
|
||
| **Document the hole prominently:** every track's PR body MUST include the following line in a "Known gaps after this PR" section: | ||
|
|
||
| > ⚠️ **Memory is not wired.** `ctx.memory` is a stub in v1; see `docs/plans/deploy-v1-schema-cascade-spec.md` § Loud hole. Memory wiring lands in a follow-up workflow (not yet specced). | ||
|
|
||
| A separate spec — `docs/plans/deploy-v1-memory-spec.md` — will own the wiring. Out of scope here. | ||
|
|
||
| ### Terminology notes (diagram ↔ schema) | ||
|
|
||
| The May 12 whimsical diagrams use a few names that differ from the locked schema. Ricky must use the **schema** names in code and migrations; diagram names are informal aliases. | ||
|
|
||
| | Diagram term | Schema term | Notes | | ||
| |---|---|---| | ||
| | `harnesses` table | `provider_credentials` | The "user-owned llm credential" row — `(user_id, model_provider, auth_type, label)`. The diagram's "harness" is the runner program (claude code, codex, opencode); the row is the credential to run it. Schema name `provider_credentials` stays. | | ||
| | `harnessShare` field | `provider_credentials.label` (or N/A) | The diagram's right-side table sketch was lossy here; treat as informal. | | ||
| | "Listeners" (image 1, item 4) + "schedule" (image 1, item 5) | `PersonaSpec.integrations.<p>.triggers[]` + `PersonaSpec.schedules[]` | Listed adjacently in image 1; spec keeps the existing shape with listeners as the unifying narrative (Track D JSDoc). | | ||
| | "Setup relaycast environment + agents.md with relaycast credentials" (image 3) | Runtime concern in cloud#548's agent-gateway, NOT a persona-spec field | Every deployed agent gets relaycast wired so it can communicate. Doesn't require the persona to declare an `inbox` listener. | | ||
|
|
||
| --- | ||
|
|
||
| ## Track A — Cloud #553 schema lock-ins (issue body + migrations PR) | ||
|
|
||
| **Repo:** `$CLOUD_REPO` (operates in place — single track on this repo at a time) | ||
| **Implementer model:** codex (high reasoning). | ||
| **Working branch:** `chore/db1-schema-lockin` | ||
| **PR title:** `feat(db): DB1 schema lock-ins per cloud#553 thread` | ||
|
|
||
| **Allowed-dirty regex:** `package(-lock)?\.json|packages/web/drizzle/.*|packages/web/lib/db/.*|packages/web/lib/proactive-runtime/.*|docs/.*` | ||
|
|
||
| ### A1 — Update issue body of cloud#553 | ||
|
|
||
| Read the current issue body first: | ||
| ```bash | ||
| gh issue view 553 --repo AgentWorkforce/cloud --json body -q .body > /tmp/553-current.md | ||
| ``` | ||
|
|
||
| Edit the body to reflect ALL of the following lock-ins. If a lock-in is already in the body (Will has applied some already), leave it; only add what's missing. | ||
|
|
||
| #### Two-table agent model (multi-instance per persona) | ||
|
|
||
| Replace the existing single `agent_deployments` definition with a two-table model: | ||
|
|
||
| **`agents`** — persona-level, addressable identity. One row per `(workspace_id, persona_id)` not yet destroyed. | ||
|
|
||
| | Column | Notes | | ||
| |---|---| | ||
| | `id` uuid PK | The addressable agent ID — used in inter-agent communication, billing, observability grouping | | ||
| | `workspace_id` uuid FK→workspaces | | | ||
| | `persona_id` uuid FK→personas | | | ||
| | `deployed_name` text | denorm of `persona.slug` at deploy time | | ||
| | `deployed_by_user_id` uuid FK→users | | | ||
| | `credential_selections` jsonb | per-provider credential pick | | ||
| | `input_values` jsonb | per-deployment overrides for `persona.spec.inputs` | | ||
| | `pinned_version_id` uuid NULL FK→persona_versions | when NULL, agent tracks persona's latest version | | ||
| | `spec_hash_at_deploy` text | for "agent is behind persona" UI | | ||
| | `status` enum | `active \| disabled \| error \| destroyed` | | ||
| | `destroyed_at` timestamptz NULL | | | ||
| | `destroyed_by_user_id` uuid NULL | | | ||
| | `spawned_by_agent_id` uuid NULL FK→agents(id) | observability when one agent spawns another | | ||
| | `last_used_at`, `last_error` | | | ||
|
|
||
| `UNIQUE (workspace_id, persona_id) WHERE status != 'destroyed'` | ||
| `UNIQUE (workspace_id, deployed_name) WHERE status != 'destroyed'` | ||
|
|
||
| **`agent_deployments`** — per-running-instance row (a "head"). Many rows per `agents.id`. Two simultaneous Linear-ticket triggers for the same agent fan out to two `agent_deployments` rows under one `agents` row. | ||
|
|
||
| | Column | Notes | | ||
| |---|---| | ||
| | `id` uuid PK | per-instance ID | | ||
| | `agent_id` uuid FK→agents | | | ||
| | `trigger_kind` text | `'inbox' \| 'clock' \| 'radio'` | | ||
| | `trigger_payload` jsonb | what fired this deployment (cron name, integration event envelope, inbox message id, etc.) | | ||
| | `started_at`, `last_active_at` timestamptz | | | ||
| | `status` enum | `running \| idle \| timed_out \| completed \| failed` | | ||
| | `spec_hash_at_run` text | snapshot of which spec version this instance executed | | ||
| | `timed_out_at` timestamptz NULL | set when this deployment times out | | ||
| | `compaction_summary` text NULL | LLM-summarized conversation written when this deployment compacts | | ||
| | `parent_deployment_id` uuid NULL FK→agent_deployments(id) | chain to prior compaction so the "thread" of a conversation is reconstructable | | ||
|
|
||
| Add a `## Multi-instance + compaction semantics` section in the issue body: | ||
|
|
||
| > A single `agents` row can have N concurrent `agent_deployments`. Two simultaneous triggers (e.g. two Linear tickets arriving for the same MSD agent) fan out to two `agent_deployments` rows. Each deployment has its own conversation context. | ||
| > | ||
| > **Timeouts are runtime-managed**, per `trigger_kind`: human DM ≈ 5 min idle, GitHub review ≈ 24h, etc. (not in persona spec for v1.) | ||
| > | ||
| > **On timeout: compaction.** Runtime runs a compaction step — LLM summarizes the conversation; `compaction_summary` written; `timed_out_at` set; status moves to `timed_out`. The next trigger creates a new `agent_deployments` row with `parent_deployment_id` pointing at the timed-out row; the new row's system prompt is seeded from the parent's `compaction_summary`. | ||
|
|
||
| #### Integrations — two-table model | ||
|
|
||
| Already in body per Will's earlier edits — verify: | ||
| - `user_integrations` + `workspace_integrations`, nullable `name`, partial-unique indexes. `workspace_service_accounts` absorbed via `name IS NOT NULL`. | ||
|
|
||
| Add if missing: | ||
| - **`adapter` column on both integration tables** — `text NOT NULL DEFAULT 'nango'`, values `'nango' | 'composio' | 'pipedream'`. Will explicitly: "There should be adapter." Cloud already brokers via Composio (`packages/web/lib/integrations/composio-service.ts`); Pipedream is in the picture too. | ||
|
|
||
| #### `integration_scopes` generic table — replaces `slack_channel_configs` | ||
|
|
||
| ``` | ||
| integration_scopes | ||
| id uuid PK | ||
| user_integration_id uuid NULL FK→user_integrations(id) | ||
| workspace_integration_id uuid NULL FK→workspace_integrations(id) | ||
| scope_kind text -- 'slack_channel' | 'github_repo' | 'jira_project' | 'notion_database' | … | ||
| scope_id text -- provider-side id (channel id, repo full_name, project key, …) | ||
| config_json jsonb -- per-kind extras (enabled flag, mode, etc.), zod-validated by scope_kind | ||
| created_at, updated_at | ||
| CHECK ((user_integration_id IS NULL) <> (workspace_integration_id IS NULL)) | ||
| UNIQUE (user_integration_id, scope_kind, scope_id) WHERE user_integration_id IS NOT NULL | ||
| UNIQUE (workspace_integration_id, scope_kind, scope_id) WHERE workspace_integration_id IS NOT NULL | ||
| ``` | ||
|
|
||
| Mirrors the two-table integration pattern via two nullable FKs + CHECK. | ||
|
|
||
| #### `persona_versions` table — in v1 | ||
|
|
||
| ``` | ||
| persona_versions | ||
| id uuid PK | ||
| persona_id uuid FK→personas | ||
| version int | ||
| spec jsonb | ||
| spec_hash text | ||
| created_at timestamptz | ||
| UNIQUE (persona_id, version) | ||
| UNIQUE (persona_id, spec_hash) | ||
| ``` | ||
|
|
||
| Add authoring note: "The persona-maker authoring agent writes a new `persona_versions` row on each persona edit. No separate version-management UI in v1." | ||
|
|
||
| `agents.spec_snapshot jsonb` is removed; replaced by `agents.pinned_version_id uuid NULL FK→persona_versions(id)`. When NULL, agent tracks persona's latest version. | ||
|
|
||
| #### `cli_auth_sessions` split | ||
|
|
||
| Rename existing table → `cloud_cli_bootstrap_sessions` (preserves Daytona + SSH bootstrap shape). | ||
|
|
||
| Add new: | ||
| ``` | ||
| workforce_cli_auth_sessions | ||
| id uuid PK | ||
| user_id uuid FK→users | ||
| code_challenge text | ||
| code_challenge_method text | ||
| state text | ||
| redirect_uri text | ||
| token_hash text NULL -- set on successful exchange; nulled on revoke | ||
| issued_at, exchanged_at, expires_at, revoked_at timestamptz | ||
| ``` | ||
|
|
||
| #### Sharing rule prose | ||
|
|
||
| Replace any "OAuth credentials cannot be shared org-wide" language with: | ||
|
|
||
| > A persona can be shared org-wide regardless of credential type. The persona itself is shareable; credentials are deployer-scoped. Deploys fail with a clear error when the deploying user hasn't connected the required credential. | ||
|
|
||
| #### GitHub App + user OAuth combine (resolution flow doc) | ||
|
|
||
| Add to §"Resolution at deployment-run time": | ||
|
|
||
| > For provider `github`, `source: { kind: 'deployer_user' }` loads the deployer's `user_integrations` row **and** the workspace's matching `workspace_integrations` row (matching workspace + provider, `name IS NULL`). Both are required at runtime: the App install gates repo access (workspace `installation_id`); the user OAuth identifies the actor. | ||
|
|
||
| #### Sub-agents / teams note | ||
|
|
||
| Add to schema doc: | ||
|
|
||
| > **Harness sub-instances** inside a handler invocation are captured in `session_events`, not new `agents` or `agent_deployments` rows. | ||
| > | ||
| > **Multi-persona teams.** When agent A spawns agent B (a different persona), B gets its own `agents` row. RelayCast workspace IS the de facto team grouping in v1; no new `agent_teams` table. `agents.spawned_by_agent_id NULL` is the observability back-pointer. | ||
|
|
||
| #### External state: sandbox-minute metering | ||
|
|
||
| Add row to the External state table: | ||
|
|
||
| | Concern | Stored in | How DB1 references it | | ||
| |---|---|---| | ||
| | Sandbox-minute usage events | platform metering pipeline (emitted via structured `logger.info` from `packages/web/app/api/v1/workspaces/[workspaceId]/sandboxes/workforce-sandbox-meter.ts`) | events carry `agent_id`, `workspace_id`, `sandbox_id`; no DB1 row; reconcile in billing dashboard | | ||
|
|
||
| #### Lock-in revision history | ||
|
|
||
| Add a `## Lock-in revision history` section at the bottom of the issue body referencing this workflow run + the May 12 transcripts + the date. | ||
|
|
||
| Apply via: | ||
| ```bash | ||
| gh issue edit 553 --repo AgentWorkforce/cloud --body-file /tmp/553-updated.md | ||
| ``` | ||
|
|
||
| ### A2 — Open migrations PR | ||
|
|
||
| Branch `chore/db1-schema-lockin` off `origin/main` in `$CLOUD_REPO`. Generate Drizzle migrations in `packages/web/drizzle/`: | ||
|
|
||
| **New tables:** | ||
| - `agents` — the persona-level identity (see schema in A1) | ||
| - `persona_versions` | ||
| - `integration_scopes` | ||
| - `user_integrations` (if not already shipped — verify) | ||
| - `workspace_integrations` (if not already shipped — absorb `workspace_service_accounts` if it exists) | ||
| - `workforce_cli_auth_sessions` | ||
|
|
||
| **Renames:** | ||
| - `cli_auth_sessions` → `cloud_cli_bootstrap_sessions` | ||
|
|
||
| **Repurpose `agent_deployments`:** the existing table moves from "persona-level deployment" semantics to "per-instance run" semantics. This is largely additive: keep `agent_deployments.id` as the per-instance ID; move persona-level columns (deployed_name, credential_selections, input_values, status, destroyed_at, etc.) to the new `agents` table. Add: | ||
| - `agent_deployments.agent_id uuid NOT NULL FK→agents(id)` | ||
| - `agent_deployments.trigger_kind text NOT NULL DEFAULT 'inbox'` (back-fill for existing rows) | ||
| - `agent_deployments.trigger_payload jsonb NULL` | ||
| - `agent_deployments.started_at`, `last_active_at` timestamptz | ||
| - `agent_deployments.timed_out_at timestamptz NULL` | ||
| - `agent_deployments.compaction_summary text NULL` | ||
| - `agent_deployments.parent_deployment_id uuid NULL FK→agent_deployments(id)` | ||
| - `agent_deployments.spec_hash_at_run text` | ||
| - `agent_deployments.status` enum updated to `running | idle | timed_out | completed | failed` | ||
|
|
||
| **Back-fill migration for existing `agent_deployments` rows:** for each existing row: | ||
| 1. Create an `agents` row, copy persona-level columns. | ||
| 2. Point the original row's new `agent_id` at it. | ||
| 3. Translate the old status enum (`active | disabled | error | destroyed`) → new statuses (`running | timed_out | failed | completed`) using a best-effort mapping (active→running, disabled→completed, error→failed, destroyed→completed with destroyed_at copied to agents). | ||
|
|
||
| **Column adds on existing tables:** | ||
| - `user_integrations.adapter text NOT NULL DEFAULT 'nango'` | ||
| - `workspace_integrations.adapter text NOT NULL DEFAULT 'nango'` | ||
|
|
||
| **Data migrations:** | ||
| - `slack_channel_configs` → `integration_scopes` with `scope_kind = 'slack_channel'`. After move, drop `slack_channel_configs`. | ||
| - `workspace_service_accounts` → `workspace_integrations` with `name = <service-account-name>`. After move, drop `workspace_service_accounts`. | ||
|
|
||
| **Constraint updates:** | ||
| - `agents` unique indexes filtered `WHERE status != 'destroyed'`. | ||
|
|
||
| **Codegen:** | ||
| - Run Drizzle codegen so the TypeScript schema (`packages/web/lib/db/schema.ts`) matches. | ||
|
|
||
| ### Track A acceptance | ||
|
|
||
| - [ ] Issue body of cloud#553 reflects every bullet above. | ||
| - [ ] `agents` table created; `agent_deployments` repurposed for per-instance rows. | ||
| - [ ] All migrations + back-fill steps land in the same PR. | ||
| - [ ] Migrations PR opens as DRAFT. | ||
| - [ ] `npm run typecheck` clean. | ||
| - [ ] `npm test` passes (existing tests; new tables not yet exercised — that's Track B). | ||
| - [ ] No `--no-verify`; all hooks pass. | ||
|
|
||
| **Effort estimate:** ~5h (back-fill migration is the bulk of the work). | ||
|
|
||
| --- | ||
|
|
||
| ## Track B — Cloud resolver: dispatch on `source` + `adapter` | ||
|
|
||
| **Repo:** `$CLOUD_REPO.wt-resolver` (worktree) | ||
| **Implementer model:** codex (medium reasoning). | ||
| **Working branch:** `feat/integration-resolver-source-dispatch` | ||
| **Base:** Track A's branch (or `main` if Track A merges first). | ||
| **Depends on:** Track A's migrations PR merged (or mergeable + schema types stable). | ||
|
|
||
| **Allowed-dirty regex:** `packages/web/lib/integrations/.*|packages/web/lib/proactive-runtime/deploy-manager\.ts|packages/web/app/api/v1/integrations/.*` | ||
|
|
||
| ### Implementation | ||
|
|
||
| Update cloud's integration resolver (find it under `packages/web/lib/integrations/` and `packages/web/lib/proactive-runtime/deploy-manager.ts`). | ||
|
|
||
| 1. **Read `source` from persona spec.** Persona-side `PersonaIntegrationConfig.source` ships in workforce#97 (rebased in Track E5). For each declared integration: | ||
| - `source.kind === 'deployer_user'` → query `user_integrations WHERE user_id = $deployer AND provider = $p AND name IS NULL`. | ||
| - `source.kind === 'workspace'` → query `workspace_integrations WHERE workspace_id = $ws AND provider = $p AND name IS NULL`. | ||
| - `source.kind === 'workspace_service_account'` → query `workspace_integrations WHERE workspace_id = $ws AND provider = $p AND name = $source.name`. | ||
| - Missing/undefined `source` → default `{ kind: 'deployer_user' }`. Mirror persona-kit's parser default-injection. | ||
|
|
||
| 2. **GitHub App combine.** When provider is `github` AND `source.kind === 'deployer_user'`, ALSO load the workspace's `workspace_integrations` row (`name IS NULL`) for the installation_id. Return a combined resolved-integration object: | ||
| ```ts | ||
| { user_oauth: UserIntegrationRow, workspace_install: WorkspaceIntegrationRow } | ||
| ``` | ||
| If the workspace install is missing, deploy must fail with: `GitHub deploys require both a user OAuth and a workspace GitHub App install. Workspace install missing.` | ||
|
|
||
| 3. **`adapter` dispatch.** When invoking the connection's token-refresh / introspection logic, branch on `integration.adapter`: | ||
| - `'nango'` → existing Nango path (unchanged). | ||
| - `'composio'` → existing Composio path in `packages/web/lib/integrations/composio-service.ts`. | ||
| - `'pipedream'` → throw `Adapter 'pipedream' not yet wired` (stub for future). | ||
|
|
||
| 4. **Default `source` injection on the cloud side.** Mirror persona-kit's behavior: any spec arriving without `source` gets `{ kind: 'deployer_user' }` injected at resolver entry. | ||
|
|
||
| ### Track B tests | ||
|
|
||
| Add resolver test fixtures (vitest): | ||
| - [ ] deployer_user happy path | ||
| - [ ] workspace happy path | ||
| - [ ] workspace_service_account happy path (named) | ||
| - [ ] GitHub combine: both rows present → success | ||
| - [ ] GitHub combine: workspace install missing → clear error | ||
| - [ ] Missing user_integrations row → clear error | ||
| - [ ] Unknown `adapter` → clean "not yet wired" error | ||
| - [ ] Default source injection when persona spec omits it | ||
| - [ ] Adapter dispatch routes correctly (Nango / Composio) | ||
|
|
||
| ### Track B acceptance | ||
|
|
||
| - [ ] Resolver dispatches by `source.kind` without inference. | ||
| - [ ] GitHub combine returns both rows when both required. | ||
| - [ ] Adapter dispatch routes to existing Nango + Composio paths. | ||
| - [ ] All new tests green; existing tests unchanged. | ||
| - [ ] `npm run typecheck && npm test` clean. | ||
|
|
||
| **Effort estimate:** ~4h. | ||
|
|
||
| --- | ||
|
|
||
| ## Track C — Cloud #548 OSS-scope rebase coordination | ||
|
|
||
| **Repo:** `$CLOUD_REPO` (no worktree — comment-only) | ||
| **Implementer model:** claude (medium reasoning). | ||
| **No branch.** Comment-only via `gh pr comment`. | ||
|
|
||
| **Note:** relay#844 already merged at 2026-05-12T19:50:04Z. `@agent-relay/events@6.0.17` and `@agent-relay/agent@6.0.17` are published on npm. A coordination comment has already been posted on cloud#548 (see comment `4434762449`). Track C is effectively **already done** at workflow start; Ricky should verify the comment exists and skip if so. | ||
|
|
||
| ### Preflight | ||
|
|
||
| ```bash | ||
| COMMENT_EXISTS=$(gh pr view 548 --repo AgentWorkforce/cloud --json comments \ | ||
| -q '.comments[] | select(.body | test("@agent-relay/events@6\\.0\\.17")) | .id' | head -1) | ||
|
|
||
| if [ -n "$COMMENT_EXISTS" ]; then | ||
| echo "SKIP: Track C already posted via comment $COMMENT_EXISTS" | ||
| exit 0 | ||
| fi | ||
| ``` | ||
|
|
||
| If somehow the comment is missing (rolled back, etc.), re-post it: | ||
|
|
||
| ```bash | ||
| gh pr comment 548 --repo AgentWorkforce/cloud -F <body-file.md> | ||
| ``` | ||
|
|
||
| with the same contents as comment `4434762449` (relay#844 merged, versions live, rebase recommendation, alternative cleanup-PR option). | ||
|
|
||
| ### Track C acceptance | ||
|
|
||
| - [ ] Coordination comment exists on cloud#548 referencing `@agent-relay/{events,agent}@6.0.17`. | ||
|
|
||
| **Effort estimate:** ~5min. | ||
|
|
||
| --- | ||
|
|
||
| ## Track D — Workforce persona-kit refactor (traits-out, sandbox-out, listeners doc) | ||
|
|
||
| **Repo:** `$WORKFORCE_REPO` (operates in place — Track D owns the primary checkout; E/F use worktrees) | ||
| **Implementer model:** codex (high reasoning). | ||
| **Working branch:** `refactor/persona-kit-schema-lockin` | ||
| **Base:** `origin/main` AFTER workforce#95 merges. | ||
|
|
||
| **Hard precondition:** | ||
| ```bash | ||
| MERGED_AT=$(gh pr view 95 --repo AgentWorkforce/workforce --json mergedAt -q '.mergedAt') | ||
| if [ -z "$MERGED_AT" ] || [ "$MERGED_AT" = "null" ]; then | ||
| echo "WAITING: workforce#95 not merged"; exit 0 | ||
| fi | ||
| ``` | ||
|
|
||
| **Allowed-dirty regex:** `packages/persona-kit/.*|packages/runtime/src/proactive\.ts|packages/runtime/src/types\.ts|packages/runtime/src/ctx\.ts|packages/deploy/src/.*|examples/.*|docs/plans/.*` | ||
|
|
||
| ### Implementation | ||
|
|
||
| 1. **Remove `traits` from `PersonaSpec`.** | ||
| - Delete `Traits` type from `packages/persona-kit/src/types.ts`. | ||
| - Delete `spec.traits` parsing logic from `packages/persona-kit/src/parse.ts`. | ||
| - Update all persona fixtures in `packages/persona-kit/src/__fixtures__/` and `examples/*/persona.json` to remove any `traits` block. | ||
| - Remove `traits`-related re-exports / imports from `packages/runtime/src/proactive.ts`. If `expressionFromTraits` (or similar) is still referenced, remove it. | ||
| - Parser must REJECT personas containing a `traits` key with a clear error: `traits was removed in v1; personality is handled by the persona-personality-builder tool (out of scope for v1). See docs/plans/deploy-v1.md`. | ||
|
|
||
| 2. **Remove `sandbox` from `PersonaSpec`.** | ||
| - Delete `SandboxConfig` type and `spec.sandbox` parsing. | ||
| - Update fixtures and examples removing any `sandbox` blocks. | ||
| - Verify `@agentworkforce/deploy` (`packages/deploy/src/index.ts` and `packages/deploy/src/modes/sandbox.ts`) reads sandbox config from deploy options (the `--mode sandbox` CLI flag and any defaults baked into the deploy package), NOT from `persona.spec`. If any code reads `spec.sandbox`, refactor. | ||
| - Parser must REJECT personas containing a `sandbox` key with a clear error: `sandbox was removed in v1; sandbox is on by default at deploy time. Use 'workforce deploy --no-sandbox' or runtime config to opt out. See docs/plans/deploy-v1.md`. | ||
|
|
||
| 3. **Listeners section rename (DOCS + COMMENTS ONLY — keep current SHAPE).** | ||
| Khaliq explicitly: "I don't know if we have to be so literal with inbox, clock, radio, current shape is probably fine, but can use listeners." | ||
| - Add JSDoc comments on `PersonaIntegrationConfig` and `Schedule` describing them as the "radio listener" and "clock listener" parts of a persona's listener surface. | ||
| - Top-level JSDoc on `PersonaSpec`: | ||
| > A persona listens for events. Three listener kinds: **clock** (cron schedules — `schedules[]`), **radio** (RelayFile integration events — `integrations.<provider>.triggers[]`), **inbox** (RelayCast targeted messages — not yet modeled in v1). The current shape predates the listeners framing; semantics are equivalent. | ||
| - Update `docs/plans/deploy-v1.md` §3 prose with the listeners narrative (recover from git if untracked: `git show 11ed713:docs/plans/deploy-v1.md > docs/plans/deploy-v1.md`). | ||
| - Do NOT restructure JSON schema. Do NOT rename existing types. | ||
|
|
||
| 4. **Regenerate persona JSON schema if applicable.** | ||
| - If `packages/persona-kit/scripts/emit-schema.mjs` exists on the branch: run it, commit the regenerated `packages/persona-kit/schemas/persona.schema.json`. | ||
| - If not, skip and note in PR body that #94 will pick it up on rebase. | ||
|
|
||
| 5. **Update tests.** | ||
| - Remove tests asserting on `traits`/`sandbox` fields. | ||
| - Add tests asserting parse FAILURE (with the specific error messages) when `traits` or `sandbox` keys appear. | ||
| - Verify the 14 personas in `packages/personas-core` still validate via `corepack pnpm -r --filter @agentworkforce/personas-core run lint`. | ||
|
|
||
| 6. **Examples cleanup.** Strip `traits` + `sandbox` from `examples/weekly-digest/persona.json`, `examples/review-agent/persona.json`, `examples/linear-shipper/persona.json` if they exist on this branch. | ||
|
|
||
| ### Track D acceptance | ||
|
|
||
| - [ ] `traits` and `sandbox` types removed from persona-kit `types.ts` and `parse.ts`. | ||
| - [ ] Parser rejects `traits` and `sandbox` with the specified errors. | ||
| - [ ] All persona fixtures + 14 core personas parse without errors. | ||
| - [ ] Listeners JSDoc + `deploy-v1.md` §3 narrative updated. | ||
| - [ ] Persona JSON schema regenerated if emit-schema is on the branch. | ||
| - [ ] `corepack pnpm -r run build && corepack pnpm run typecheck && corepack pnpm -r run test` green. | ||
| - [ ] PR opens as DRAFT. | ||
|
|
||
| **Effort estimate:** ~2.5h. | ||
|
|
||
| --- | ||
|
|
||
| ## Track E — Workforce queue rebase (#92, #93, #94, #96, #97) | ||
|
|
||
| **Repo:** `$WORKFORCE_REPO.wt-rebase-<N>` (one worktree per PR) | ||
| **Implementer model:** codex (medium reasoning). | ||
| **Depends on:** Track D merged. | ||
|
|
||
| For each PR in the workforce queue, rebase its branch onto post-Track-D `main`. Resolve conflicts from traits/sandbox removal. Do NOT introduce new functionality. Push with `git push --force-with-lease`. | ||
|
|
||
| ### Sub-tracks | ||
|
|
||
| | ID | PR | Branch | Worktree | Rebase action | | ||
| |---|---|---|---|---| | ||
| | **E1** | #92 | `feat/integrations-vfs` | `wt-rebase-92` | Rebase. VFS substrate doesn't touch traits/sandbox; conflicts should be minimal. | | ||
| | **E2** | #93 | `feat/integrations-vfs-examples` | `wt-rebase-93` | Rebase + strip `traits` and `sandbox` blocks from `examples/review-agent/persona.json` and `examples/linear-shipper/persona.json`. Verify both still type-check against #92's `WorkforceCtx`. | | ||
| | **E3** | #94 | `feat/persona-json-schema` | `wt-rebase-94` | Rebase + run `scripts/emit-schema.mjs` to regenerate `packages/persona-kit/schemas/persona.schema.json`. Verify fixtures still validate. | | ||
| | **E4** | #96 | `feat/proactive-bridge` | `wt-rebase-96` | Rebase. Drop any remaining `expressionFromTraits` references. Bump `@agent-assistant/proactive ^0.4.31 → ^0.4.32` per agent-assistant#91 publish; run `corepack pnpm install` to refresh `pnpm-lock.yaml`. Verify the existing test baseline passes. | | ||
| | **E5** | #97 | `feat/persona-integration-source` | `wt-rebase-97` | Rebase. Interface name is `PersonaIntegrationConfig` (verified in #97). No content change beyond rebase. | | ||
|
|
||
| ### Per-sub-track gates (soft → fixer → hard) | ||
|
|
||
| ```bash | ||
| corepack pnpm -r run build | ||
| corepack pnpm run typecheck | ||
| corepack pnpm -r run test | ||
| ``` | ||
|
|
||
| ### Track E acceptance (per sub-track) | ||
|
|
||
| - [ ] Rebased branch pushes successfully with `--force-with-lease`. | ||
| - [ ] CI on the PR is green after rebase. | ||
| - [ ] No functional regression vs the PR's original acceptance bullets. | ||
| - [ ] If conflicts unresolvable: open `<original-branch>-rebased`, post a comment on the original linking it, STOP that sub-track. Others continue. | ||
|
|
||
| **Effort estimate:** ~1h per sub-track; E1–E5 can run in parallel after Track D. | ||
|
|
||
| --- | ||
|
|
||
| ## Track F — Workforce runtime input-values + agent identity wiring | ||
|
|
||
| **Repo:** `$WORKFORCE_REPO.wt-runtime` (worktree) | ||
| **Implementer model:** codex (medium reasoning). | ||
| **Working branch:** `feat/runtime-input-values-resolution` | ||
| **Base:** post-Track-D `main`. | ||
| **Depends on:** Track D merged AND Track A's migrations PR merged (need `agents.input_values` column). | ||
|
|
||
| **Allowed-dirty regex:** `packages/runtime/src/ctx\.ts|packages/runtime/src/types\.ts|packages/runtime/src/ctx\.test\.ts|packages/runtime/src/__tests__/.*` | ||
|
|
||
| ### Implementation | ||
|
|
||
| In `packages/runtime/src/ctx.ts`: | ||
|
|
||
| 1. **Read `input_values` from the `agents` row** (NOT `agent_deployments` — input values are agent-level, not per-instance). | ||
| ``` | ||
| resolved[key] = agents.input_values[key] ?? persona.spec.inputs[key].default | ||
| ``` | ||
| When a required input has no value from either source, throw before the handler runs: | ||
| ``` | ||
| Required input '<key>' has no value (no deployment override, no spec default). Set it via 'workforce deploy --input <key>=<value>' or by editing the agent record. | ||
| ``` | ||
|
|
||
| 2. **Update `WorkforceCtx.persona.inputs` shape** (`types.ts`): | ||
| - Currently exposes `Record<string, PersonaInputSpec>` (defaults). | ||
| - New: expose `Record<string, string>` (resolved values). | ||
| - Add `ctx.persona.inputSpecs: Record<string, PersonaInputSpec>` for consumers that need the spec. | ||
|
|
||
| 3. **Add `ctx.agent` and `ctx.deployment` accessors** to mirror the schema: | ||
| ```ts | ||
| ctx.agent: { id: string; deployedName: string; spawnedByAgentId: string | null; ... } | ||
| ctx.deployment: { id: string; triggerKind: 'inbox' | 'clock' | 'radio'; parentDeploymentId: string | null; ... } | ||
| ``` | ||
| The runtime injects these from the agent + agent_deployment rows that fired this handler. | ||
|
|
||
| 4. **Tests:** | ||
| - [ ] Override wins over default. | ||
| - [ ] Default fills when override absent. | ||
| - [ ] Required input with no value → throws specified error. | ||
| - [ ] `ctx.persona.inputSpecs` still exposes the spec defaults. | ||
| - [ ] `ctx.agent.id` + `ctx.deployment.id` correctly populated. | ||
|
|
||
| ### Track F acceptance | ||
|
|
||
| - [ ] `ctx.persona.inputs` returns resolved values. | ||
| - [ ] Required-but-missing inputs throw with the specified error. | ||
| - [ ] `ctx.persona.inputSpecs` accessor added. | ||
| - [ ] `ctx.agent` and `ctx.deployment` accessors added. | ||
| - [ ] `corepack pnpm -r run build && corepack pnpm -r run test` green. | ||
| - [ ] PR title: `feat(runtime): resolve persona inputs from agents.input_values + expose ctx.agent/ctx.deployment` | ||
| - [ ] Opens as DRAFT. | ||
|
|
||
| **Effort estimate:** ~2h. | ||
|
|
||
| --- | ||
|
|
||
| --- | ||
|
|
||
| # Phase 2 — Deploy enablement tracks | ||
|
|
||
| Phase 1 (Tracks A–F) lands the schema, persona-kit refactor, runtime accessors, and queue rebase. **Phase 2 lights up end-to-end deploy** — cloud accepts a persona+bundle payload, workforce CLI speaks that contract OSS-generically, deploy-time inputs are wired, and the MCP `workflow.run` tool actually returns results. | ||
|
|
||
| Phase 2 tracks depend on Phase 1 tracks being merged. Order: G → H (workforce-side consumer of G's contract); I depends on A (schema) + D (persona-kit); J depends on cloud#555 being live on main. | ||
|
|
||
| ## Track G — Cloud persona+bundle deploy endpoint | ||
|
|
||
| **Repo:** `$CLOUD_REPO.wt-deploy-endpoint` (worktree) | ||
| **Implementer model:** codex (high reasoning). | ||
| **Working branch:** `feat/persona-bundle-deploy-endpoint` | ||
| **Base:** Track A merged (`agents` + `agent_deployments` schema live); cloud#548 ideally merged (for agent-gateway + DO infra) but the endpoint can ship as a stub that queues for the gateway if #548 is still in flight. | ||
|
|
||
| **Depends on:** | ||
| - Track A merged. | ||
| - cloud#548 merged (for agent-gateway DO + `relaycron-client.ts` + `registerWatches` infra). | ||
| - **relaycron#5 merged** — without this, the WS-delivery + cancel API in relaycron isn't live, and schedule registration via cloud's `relaycron-client.ts` returns errors at runtime. Preflight check: | ||
| ```bash | ||
| RC5_MERGED=$(gh pr view 5 --repo AgentWorkforce/relaycron --json mergedAt -q '.mergedAt') | ||
| if [ -z "$RC5_MERGED" ] || [ "$RC5_MERGED" = "null" ]; then | ||
| echo "WAITING: relaycron#5 not merged"; exit 0 | ||
| fi | ||
| ``` | ||
|
|
||
| **Allowed-dirty regex:** `packages/web/app/api/v1/workspaces/\[workspaceId\]/deployments/.*|packages/web/lib/proactive-runtime/.*|packages/web/lib/.*persona.*|services/agent-gateway/.*` | ||
|
|
||
| ### Why this exists | ||
|
|
||
| cloud#548's `/api/v1/deploy` takes `{ entrypoint, source }` — single-file TS. workforce's deploy CLI is built to upload a persona+bundle. The decision (Khaliq): **cloud adds a new endpoint for the persona+bundle contract.** Single-file `/api/v1/deploy` stays for power users; persona+bundle is the workforce-CLI surface. | ||
|
|
||
| ### Endpoint contract | ||
|
|
||
| ``` | ||
| POST /api/v1/workspaces/:workspaceId/deployments | ||
| Auth: workspace token (mirror sandbox endpoint auth scopes) | ||
| Body: | ||
| { | ||
| persona: PersonaSpec, // full persona JSON, validated via @agentworkforce/persona-kit | ||
| bundle: { | ||
| runner: string, // contents of runner.mjs | ||
| agent: string, // contents of agent.bundle.mjs (esbuild output) | ||
| packageJson: object // contents of package.json | ||
| }, | ||
| inputs?: Record<string, string>, // initial input values for agents.input_values | ||
| pinnedVersion?: { version: number } // optional; if set, pin to that persona_versions row | ||
| } | ||
| Returns 201: | ||
| { | ||
| agentId: string, // agents.id | ||
| workspaceId: string, | ||
| status: 'starting' | 'active' | 'failed', | ||
| deploymentId: string // first agent_deployments row created at boot | ||
| } | ||
| ``` | ||
|
|
||
| ### Implementation | ||
|
|
||
| 1. **Validate** `persona` via `@agentworkforce/persona-kit`'s `parsePersonaSpec`. Fail with field-pointed errors on schema problems. | ||
|
|
||
| 2. **Persist `persona_versions` row.** Compute `spec_hash`; insert a new `persona_versions` row if no existing row matches (`UNIQUE (persona_id, spec_hash)`). Set `pinned_version_id` on the agent row to this new version. | ||
|
|
||
| 3. **Upsert `agents` row.** Match on `(workspace_id, persona_id)` where `status != 'destroyed'`: | ||
| - If exists → update `pinned_version_id`, `input_values`, `spec_hash_at_deploy`, bump `last_used_at`. | ||
| - If not → insert new row with `status='active'`. | ||
|
|
||
| 4. **Translate `persona.integrations.<provider>.triggers[]` → watch glob list.** The convention the agent-gateway DO and `@agent-relay/agent`'s `registerWatches` expect is glob paths under provider namespaces (e.g. `/github/pull_requests/**`). Read `services/agent-gateway/src/durable-object.ts` + `packages/agent-relay-agent/src/index.ts` to confirm the exact glob format. Translation rule: | ||
|
|
||
| ``` | ||
| provider=github, trigger.on='pull_request.opened' → /github/pull_requests/opened/** | ||
| provider=linear, trigger.on='issue.created' → /linear/issues/created/** | ||
| provider=slack, trigger.on='app_mention' → /slack/app_mention/** | ||
| ``` | ||
|
|
||
| Build a lookup table from RelayFile adapter docs (`relayfile-adapters/packages/*/docs/` if present). For unknown provider/trigger combinations, fail deploy with a clear error. | ||
|
|
||
| 5. **Persist watch globs** on the `agents` row OR in a sidecar — depends on how cloud#548's deploy-manager stores them. Most likely: store on `agents.watch_globs text[] NULL` (add to Track A if not already there) so the agent-gateway can pull them at agent boot. **Update Track A's migrations to add this column.** | ||
|
|
||
| 6. **Translate `persona.schedules[]` → relaycron registrations.** Call `services/agent-gateway/src/relaycron-client.ts:registerCronSchedules()` with each schedule, scoped by `agentId`. Persist returned `gatewayScheduleId`s on `agents.schedule_ids text[]` (add to Track A migrations). | ||
|
|
||
| 7. **Provision Daytona sandbox + upload bundle.** Use the existing `POST /api/v1/workspaces/:id/sandboxes` (cloud#543) infrastructure. Write the bundle files (`runner.mjs`, `agent.bundle.mjs`, `persona.json`, `package.json`) to the sandbox via the existing files-proxy route. | ||
|
|
||
| 8. **Start the runner.** Call the sandbox's exec route with `node runner.mjs`. The runner internally calls `agent({...})` which calls `registerWatches` against the gateway, completing the watch subscription. | ||
|
|
||
| 9. **Insert initial `agent_deployments` row** with `status='running'`, `trigger_kind='inbox'` (or the trigger that launched it), `started_at=now`. | ||
|
|
||
| 10. **Audit-log** every deployment creation (mirror sandbox endpoint audit pattern). | ||
|
|
||
| ### Track G tests | ||
|
|
||
| - [ ] Happy path: valid persona+bundle → 201 with agentId | ||
| - [ ] Re-deploy same persona → agentId stable; persona_versions has new row only if spec_hash differs | ||
| - [ ] Invalid persona (e.g. has `traits`) → 400 with field-pointed error | ||
| - [ ] Trigger translation: known github/linear/slack/notion/jira triggers map correctly | ||
| - [ ] Unknown trigger → 400 with clear error | ||
| - [ ] Cron schedules registered with relaycron (mock relaycron client) | ||
| - [ ] Daytona sandbox creation + bundle upload happen in order | ||
| - [ ] Auth: missing workspace token → 401; wrong scope → 403 | ||
|
|
||
| ### Track G acceptance | ||
|
|
||
| - [ ] Endpoint added at `POST /api/v1/workspaces/:workspaceId/deployments`. | ||
| - [ ] Persona validation, version persistence, agent upsert, trigger translation, schedule registration all wired. | ||
| - [ ] Sandbox provisioning + bundle upload + runner start work end-to-end against a test workspace. | ||
| - [ ] All new tests green; no regressions on cloud#548's existing `/api/v1/deploy` endpoint. | ||
| - [ ] PR opens as DRAFT. | ||
| - [ ] Required Track A schema additions (`agents.watch_globs`, `agents.schedule_ids`) included in Track A's migration PR. | ||
|
|
||
| **Effort estimate:** ~6h. | ||
|
|
||
| --- | ||
|
|
||
| ## Track H — Workforce `--mode cloud` (OSS-generic implementation) | ||
|
|
||
| **Repo:** `$WORKFORCE_REPO.wt-mode-cloud` (worktree) | ||
| **Implementer model:** codex (medium reasoning). | ||
| **Working branch:** `feat/deploy-mode-cloud` | ||
| **Base:** post-Track-D `main` (after persona-kit refactor). | ||
| **Depends on:** Track D merged. Track G's endpoint contract STABLE (need not be merged on cloud; can stub against the spec). | ||
|
|
||
| **Allowed-dirty regex:** `packages/deploy/src/modes/cloud\.ts|packages/deploy/src/index\.ts|packages/deploy/src/login\.ts|packages/cli/src/cli\.ts` | ||
|
|
||
| ### OSS / cloud split rationale | ||
|
|
||
| The workforce deploy CLI is OSS. Anyone running a workforce-compatible runtime (their own AWS, on-prem, anything) speaks the **persona+bundle contract** with whatever cloud endpoint URL is configured. The deploy CLI does NOT bake in `agentrelay.com`. The CLI ships generic; cloud (the proprietary side) implements the endpoint. | ||
|
|
||
| - **workforce (OSS)** — Track H: this track. Replace the stubbed `packages/deploy/src/modes/cloud.ts` with a real implementation that POSTs persona+bundle to a configurable cloud-deploy URL. | ||
| - **cloud (proprietary)** — Track G: cloud-specific endpoint implementation (above). | ||
|
|
||
| ### Decision-tree mapping (image 2) | ||
|
|
||
| Track H implements the full deploy decision tree from image 2 of the May 12 whimsical diagram. Each step in the tree maps to a stage in the CLI flow: | ||
|
|
||
| ``` | ||
| agentworkforce deploy <persona-path> | ||
| │ | ||
| ├─► STAGE 1: Choose runtime | ||
| │ ├─ --cloud-url flag → use that | ||
| │ ├─ WORKFORCE_CLOUD_URL env → use that | ||
| │ ├─ persona.cloud.deployUrl → use that | ||
| │ └─ default → https://agentrelay.com (note: "build your own" docs link printed when default is overridden) | ||
| │ | ||
| ├─► STAGE 2: Logged in? | ||
| │ ├─ no → open browser to <cloudUrl>/cli-auth (relayauth PKCE flow) | ||
| │ │ save returned token to OS keychain | ||
| │ └─ yes → use token saved on machine | ||
| │ | ||
| ├─► STAGE 3: Harness availability check | ||
| │ For each harness the persona declares (claude/codex/opencode): | ||
| │ Query GET <cloudUrl>/api/v1/users/me/provider_credentials?model_provider=<derived> | ||
| │ ├─ have a connected credential → continue | ||
| │ └─ none → | ||
| │ Prompt: "Do you want to set up your harness's subscription? (Y/n)" | ||
| │ ├─ yes → trigger provider_oauth flow (existing /provider_credentials/auth-session endpoint) | ||
| │ └─ no → | ||
| │ Prompt: "AgentRelay plan or BYOK?" | ||
| │ ├─ plan → set auth_type='relay_managed' (cloud uses its key, tracks spend, charges markup) | ||
| │ └─ BYOK → prompt for API key; save encrypted via cloud /provider_credentials POST (auth_type='byo_api_key') | ||
| │ | ||
| ├─► STAGE 4: Review listeners, determine required integrations | ||
| │ For each persona.integrations.<provider>: | ||
| │ Query GET <cloudUrl>/api/v1/workspaces/:id/integrations?provider=<p> | ||
| │ ├─ connected → continue | ||
| │ └─ missing → open browser to <cloudUrl>/integrations?provider=<p>&workspace=<id>&return_to=<cli-callback> | ||
| │ block until OAuth callback completes | ||
| │ | ||
| ├─► STAGE 5: Persona exists? | ||
| │ Query GET <cloudUrl>/api/v1/workspaces/:id/agents?persona_slug=<persona.id> | ||
| │ ├─ no → continue to deploy | ||
| │ └─ yes → | ||
| │ Prompt: "This persona is already deployed as agent <agentId> (status: <status>). | ||
| │ Update existing, destroy and create new, or cancel?" | ||
| │ ├─ update → continue to deploy (UNIQUE constraint will UPSERT) | ||
| │ ├─ destroy → POST <cloudUrl>/api/v1/workspaces/:id/agents/:agentId/destroy (M3 endpoint, may not be wired — if missing, exit with "destroy not yet wired; cancel and run with --force-replace later") | ||
| │ └─ cancel → exit 0 | ||
| │ | ||
| └─► STAGE 6: POST persona+bundle to Track G's endpoint | ||
| See implementation below. | ||
| ``` | ||
|
|
||
| For non-interactive use (CI / scripts), the CLI accepts flag overrides for every interactive prompt: | ||
| - `--no-prompt` — fail fast on any decision that would normally prompt (instead of asking). | ||
| - `--harness-source plan|byok|oauth` — pre-answer Stage 3 decisions. | ||
| - `--byok-key <key>` — pre-answer BYOK prompt. | ||
| - `--on-exists update|destroy|cancel` — pre-answer Stage 5 decision (default: `cancel`). | ||
|
|
||
| ### Implementation | ||
|
|
||
| In `packages/deploy/src/modes/cloud.ts`: | ||
|
|
||
| 1. **Resolve cloud-deploy URL** as Stage 1 above. | ||
|
|
||
| 2. **Load workspace token** from keychain via `packages/deploy/src/login.ts` (the relayauth PKCE flow already shipped in workforce#90). If absent and not `--no-prompt`, trigger login as Stage 2. | ||
|
|
||
| 3. **Run Stages 3-5** with the prompt logic above (or flag overrides for non-interactive mode). | ||
|
|
||
| 4. **POST persona+bundle (Stage 6):** | ||
| ```ts | ||
| const res = await fetch(`${cloudUrl}/api/v1/workspaces/${workspaceId}/deployments`, { | ||
| method: 'POST', | ||
| headers: { | ||
| authorization: `Bearer ${workspaceToken}`, | ||
| 'content-type': 'application/json', | ||
| }, | ||
| body: JSON.stringify({ | ||
| persona, | ||
| bundle: { | ||
| runner: await fs.readFile(bundle.runnerPath, 'utf8'), | ||
| agent: await fs.readFile(bundle.bundlePath, 'utf8'), | ||
| packageJson: JSON.parse(await fs.readFile(bundle.packageJsonPath, 'utf8')), | ||
| }, | ||
| inputs: input.inputs, // populated by Track I's --input flags | ||
| }), | ||
| }); | ||
| if (!res.ok) throw new Error(`Cloud deploy failed: ${res.status} ${await res.text()}`); | ||
| const { agentId, status, deploymentId } = await res.json(); | ||
| ``` | ||
|
|
||
| 5. **Status polling.** After POST returns `status: 'starting'`, poll `GET /api/v1/workspaces/:id/agents/:agentId` until `status='active'` or `'failed'` (60s timeout). Stream updates via `onLog`. | ||
|
|
||
| 6. **Return a `CloudRunHandle`** that exposes `{ agentId, stop(): Promise<void>, done: Promise<...> }`. `stop()` calls the M3 destroy endpoint; if not wired, throw cleanly. | ||
|
|
||
| 7. **Remove the "not yet available" stub** from `packages/deploy/src/index.ts`. | ||
|
|
||
| 8. **Add the `--cloud-url`, `--no-prompt`, `--harness-source`, `--byok-key`, `--on-exists` CLI flags** to `packages/cli/src/cli.ts`'s `deploy` case. | ||
|
|
||
| ### Track H tests | ||
|
|
||
| - [ ] Happy path: persona + bundle POST → returns CloudRunHandle with agentId. | ||
| - [ ] Cloud URL override via flag, env, persona field, default — precedence tested. | ||
| - [ ] 401 from cloud → clean error suggesting `workforce login`. | ||
| - [ ] Network error → retry with backoff (3 attempts). | ||
| - [ ] Status polling resolves on `active` and `failed`. | ||
| - [ ] `stop()` calls DELETE endpoint. | ||
|
|
||
| ### Track H acceptance | ||
|
|
||
| - [ ] `workforce deploy --mode cloud` no longer prints "not yet available." | ||
| - [ ] Posts to the configured cloud URL with persona+bundle contract. | ||
| - [ ] OSS-generic: no `agentrelay.com` baked into code paths (only as a default URL). | ||
| - [ ] PR opens as DRAFT. | ||
|
|
||
| **Effort estimate:** ~3h. | ||
|
|
||
| --- | ||
|
|
||
| ## Track I — Deploy CLI `--input <key>=<value>` flags | ||
|
|
||
| **Repo:** `$WORKFORCE_REPO.wt-deploy-inputs` (worktree) | ||
| **Implementer model:** codex (medium reasoning). | ||
| **Working branch:** `feat/deploy-input-flags` | ||
| **Base:** post-Track-D `main`. | ||
| **Depends on:** Track D merged. Track A merged (need `agents.input_values` column). Track F merged (runtime reads from `input_values`). | ||
|
|
||
| **Allowed-dirty regex:** `packages/cli/src/cli\.ts|packages/deploy/src/index\.ts|packages/deploy/src/types\.ts|packages/deploy/src/modes/.*` | ||
|
|
||
| ### Implementation | ||
|
|
||
| 1. **Accept `--input <key>=<value>` flag in `packages/cli/src/cli.ts`** (repeatable). Parse into `Record<string, string>`. Reject malformed flags with a clear error. | ||
|
|
||
| 2. **Plumb through `packages/deploy/src/index.ts`'s `deploy()` function** as `DeployOptions.inputs?: Record<string, string>`. | ||
|
|
||
| 3. **Validate against persona spec at deploy time.** For each provided input key: | ||
| - Must be declared in `persona.spec.inputs` — else fail with `Unknown input '<key>'; persona declares: <list>`. | ||
| - Value must be a string (basic type check; persona-kit may add more later). | ||
|
|
||
| 4. **Forward to each mode:** | ||
| - `--mode dev`: pass as env vars to the spawned child process (`WORKFORCE_INPUT_<KEY>=<value>`). | ||
| - `--mode sandbox`: pass as env vars to the Daytona sandbox (`envVars` arg). | ||
| - `--mode cloud`: include in the POST body's `inputs` field (Track H consumes this). | ||
|
|
||
| 5. **Update persona spec docs in `docs/plans/deploy-v1.md` §3** to mention `--input` as the deploy-time override mechanism. | ||
|
|
||
| ### Track I tests | ||
|
|
||
| - [ ] Single `--input` parses and forwards. | ||
| - [ ] Multiple `--input` flags accumulate. | ||
| - [ ] Malformed flag (`--input foo`) → clean error. | ||
| - [ ] Undeclared input key → clean error citing persona's declared inputs. | ||
| - [ ] `--mode dev` env vars actually reach the child process. | ||
| - [ ] `--mode cloud` POST body includes the `inputs` field. | ||
|
|
||
| ### Track I acceptance | ||
|
|
||
| - [ ] `workforce deploy --input topic=AI --input region=us-east-1 ./persona.json` works against all three modes. | ||
| - [ ] Undeclared inputs fail fast with a clear error. | ||
| - [ ] PR opens as DRAFT. | ||
|
|
||
| **Effort estimate:** ~1.5h. | ||
|
|
||
| --- | ||
|
|
||
| ## Track J — `workflow.run` MCP synthesis + scope mint (cloud#555 follow-ups) | ||
|
|
||
| **Repo:** `$CLOUD_REPO.wt-workflow-shim-followups` (worktree) | ||
| **Implementer model:** codex (high reasoning). | ||
| **Working branch:** `feat/workflow-invocations-followups` | ||
| **Base:** cloud#555 merged (the URL surface). | ||
| **Depends on:** cloud#555 merged. | ||
|
|
||
| **Allowed-dirty regex:** `packages/web/app/api/v1/workspaces/\[workspaceId\]/workflows/.*|packages/web/lib/workflows/.*|packages/web/lib/auth/.*sandbox.*` | ||
|
|
||
| ### Why this exists | ||
|
|
||
| cloud#555 shipped `POST /api/v1/workspaces/:id/workflows/run` taking `{ name, args }`, but it returns 501 for any registered slug — because the heavy `/api/v1/workflows/run` requires `s3CodeKey`/`sourceFileType`/`runtime` fields that can't be derived from `{ name, args }`. Two follow-ups to actually light it up: | ||
|
|
||
| ### J1 — Synthesis policy + named-workflow registry | ||
|
|
||
| Implement a slug → workflow translation in `packages/web/lib/workflows/invocation-registry.ts` (created in #555). Convention: | ||
|
|
||
| - **Named workflows live at a known S3 prefix.** Every named workflow has a pre-staged tarball at `s3://workflows/<slug>/latest.tar.gz` (or similar — match what the heavy workflow engine expects). The synthesis fills in `s3CodeKey: 'workflows/<slug>/latest.tar.gz'`. | ||
| - **`sourceFileType` defaults to `'workflow'`** unless the slug's registry entry overrides it. | ||
| - **`runtime` defaults to `{ id: 'daytona' }`** from the workspace's `default_runtime` column (the cloud-side dispatch target Will explained earlier). | ||
| - **`args`** from the MCP tool call is forwarded as `metadata.invocationArgs` to the heavy engine, since the heavy engine doesn't have a first-class args field. | ||
|
|
||
| Add an initial registry of named workflows. Start with one slug (e.g. `'echo'` — a minimal workflow that just echoes args back) so the round-trip can be smoke-tested. | ||
|
|
||
| Implementer should read the existing heavy `/api/v1/workflows/run/route.ts` to confirm the exact `RunRequestBody` synthesis. If a required field genuinely can't be synthesized, surface in PR body. | ||
|
|
||
| ### J2 — Scope mint additions | ||
|
|
||
| The sandbox-token mint flow at `packages/web/app/api/v1/workflows/run/route.ts` currently mints `workflow:runs:read`, `workflow:logs:read`, `workflow:runs:events:write`. The MCP server expects to call the new lightweight endpoints, which require `workflow:invoke:write` (for `workflow.run`) and `workflow:invoke:read` (for `workflow.status`). | ||
|
|
||
| Add these scopes to the mint: | ||
| - `workflow:invoke:write` — minted on sandbox creation for any workspace running a proactive runtime agent. | ||
| - `workflow:invoke:read` — same. | ||
|
|
||
| Ensure `requireAuthScope` checks in the new `/workspaces/:id/workflows/run` and `/workspaces/:id/workflows/runs/:runId` routes accept these scopes. | ||
|
|
||
| ### Track J tests | ||
|
|
||
| - [ ] J1: `POST /workspaces/:id/workflows/run` with `name='echo', args={foo:1}` returns a runId; the heavy engine receives a synthesized RunRequestBody. | ||
| - [ ] J1: Unknown slug → 404 with list of known slugs. | ||
| - [ ] J2: A sandbox token without `workflow:invoke:write` → 403 on POST. | ||
| - [ ] J2: Token with the right scope → success path. | ||
| - [ ] End-to-end: MCP `workflow.run` call from a Daytona sandbox actually returns a runId, no longer 501. | ||
|
|
||
| ### Track J acceptance | ||
|
|
||
| - [ ] `workflow.run` MCP tool returns a real runId for at least one registered slug (`echo` is fine for v1). | ||
| - [ ] Scope mint includes the two new scopes for sandbox tokens. | ||
| - [ ] PR opens as DRAFT. | ||
| - [ ] cloud#555's `Status: Ready for Review` note updated to reflect that J1+J2 lit it up. | ||
|
|
||
| **Effort estimate:** ~3.5h. | ||
|
|
||
| --- | ||
|
|
||
| ## Acceptance contract (workflow-level) | ||
|
|
||
| After ALL tracks (Phase 1 + Phase 2) complete: | ||
|
|
||
| ### Phase 1 | ||
| 1. cloud#553 issue body reflects every lock-in (Track A1). | ||
| 2. Cloud migrations PR (Track A2) is open as DRAFT, CI green; `agents` table created, `agent_deployments` repurposed for per-instance rows. | ||
| 3. Cloud resolver PR (Track B) is open as DRAFT, CI green; dispatches on `source` + `adapter`. | ||
| 4. cloud#548 has the relay#844 coordination comment (Track C — already posted). | ||
| 5. Workforce persona-kit PR (Track D) is open as DRAFT, CI green; traits + sandbox removed. | ||
| 6. Workforce queue (#92, #93, #94, #96, #97) is all rebased + green. | ||
| 7. Workforce runtime PR (Track F) is open as DRAFT, CI green; ctx.agent + ctx.deployment + resolved inputs. | ||
|
|
||
| ### Phase 2 | ||
| 8. Cloud persona+bundle endpoint PR (Track G) is open as DRAFT, CI green; validates persona, persists version, upserts agent, registers schedules, translates triggers, provisions sandbox. | ||
| 9. Workforce `--mode cloud` PR (Track H) is open as DRAFT, CI green; speaks Track G's contract OSS-generically. | ||
| 10. Workforce `--input` flags PR (Track I) is open as DRAFT, CI green; flows through all three modes. | ||
| 11. Workflow-invocations follow-ups PR (Track J) is open as DRAFT, CI green; `workflow.run` MCP tool returns real runIds. | ||
|
|
||
| ### Loud holes after this workflow | ||
|
|
||
| - ⚠️ **Memory is not wired.** `ctx.memory` is a stub. Follow-up workflow needed. | ||
| - ⚠️ **M3 destroy/list CLI commands** not implemented. Out of scope; M3 milestone workflow. | ||
| - ⚠️ **`@workforce/daytona-runner` not on npm** under `@workforce` scope. Handled by a separate agent per platform-team OIDC setup; not blocking morning state because cloud consumes via workspace ref. | ||
|
|
||
| --- | ||
|
|
||
| ## Track K — End-to-end smoke test | ||
|
|
||
| **Repo:** `$WORKFORCE_REPO.wt-smoke` (worktree) | ||
| **Implementer model:** codex (medium reasoning). | ||
| **Working branch:** `test/deploy-v1-e2e-smoke` | ||
| **Base:** post-everything-merged `main`. | ||
| **Depends on:** All Phase 1 + Phase 2 tracks merged. cloud#548 + relaycron#5 + relay#843 merged. | ||
|
|
||
| **Allowed-dirty regex:** `packages/deploy/test/e2e/.*|\.github/workflows/deploy-e2e\.yml` | ||
|
|
||
| ### Why this exists | ||
|
|
||
| When Khaliq wakes up, the workflow should have proved that everything actually works end-to-end, not just compiled. This track runs a real deploy against staging cloud and asserts the agent fires on a real trigger. | ||
|
|
||
| ### Implementation | ||
|
|
||
| Add `packages/deploy/test/e2e/weekly-digest.smoke.test.ts`: | ||
|
|
||
| 1. **Build the bundle locally** for `examples/weekly-digest/persona.json`: | ||
| ```ts | ||
| const bundle = await stageBundle({ | ||
| personaPath: path.resolve('examples/weekly-digest/persona.json'), | ||
| persona: parsePersonaSpec(/* loaded */), | ||
| outDir: '.workforce/build/smoke-weekly-digest', | ||
| }); | ||
| ``` | ||
|
|
||
| 2. **Authenticate** using `WORKFORCE_E2E_STAGING_TOKEN` from env (CI secret). Skip the test gracefully if missing. | ||
|
|
||
| 3. **Deploy via Track H's `--mode cloud`** against the staging cloud URL (`WORKFORCE_E2E_STAGING_URL`). | ||
|
|
||
| 4. **Force a cron tick** by directly POSTing to the runtime test hook (`POST /api/v1/workspaces/:id/agents/:agentId/_test/tick`, mirror what cloud#548 exposes — if no hook, skip the trigger and assert deployment was created + status='active' instead). | ||
|
|
||
| 5. **Assert** the agent posts a GitHub issue on the fixture repo `AgentWorkforce/deploy-e2e-fixtures` within 90s, with title pattern `Weekly digest — *`. | ||
|
|
||
| 6. **Cleanup**: close the issue, optionally destroy the agent (skip if M3 destroy isn't wired). | ||
|
|
||
| 7. **Add `.github/workflows/deploy-e2e.yml`** running this on nightly schedule + manual dispatch. Failures notify `#workforce-alerts`. | ||
|
|
||
| ### Run during workflow | ||
|
|
||
| The workflow runs Track K's smoke test ONCE after all upstream tracks have merged — but does NOT block the cascade on it. The smoke test result is reported separately as `SMOKE_TEST: PASS` or `SMOKE_TEST: FAIL — see logs`. If it fails for environmental reasons (staging Daytona down, OAuth tokens missing, fixture repo unreachable), the workflow logs but doesn't unwind any merges. | ||
|
|
||
| ### Track K acceptance | ||
|
|
||
| - [ ] Smoke test file added. | ||
| - [ ] Test passes when run against staging (or skipped cleanly if `WORKFORCE_E2E_STAGING_TOKEN` is unset). | ||
| - [ ] GitHub Actions workflow added. | ||
| - [ ] PR title: `test(deploy): e2e smoke for weekly-digest --mode cloud`. | ||
|
|
||
| **Effort estimate:** ~3h. | ||
|
|
||
| --- | ||
|
|
||
| ## Workforce PR queue triage (existing PRs the workflow handles) | ||
|
|
||
| The workflow operates on these existing workforce PRs in addition to the new tracks above. Each is either rebased + auto-merged in Track E, or explicitly skipped. | ||
|
|
||
| | PR | Branch | Track in this workflow | Auto-merge? | | ||
| |---|---|---|---| | ||
| | #97 | feat/persona-integration-source | Track E5 (rebase) | YES | | ||
| | #96 | feat/proactive-bridge | Track E4 (rebase + agent-assistant bump) | YES | | ||
| | #94 | feat/persona-json-schema | Track E3 (rebase + schema regen) | YES | | ||
| | #93 | feat/integrations-vfs-examples | Track E2 (rebase + strip traits/sandbox) | YES | | ||
| | #92 | feat/integrations-vfs | Track E1 (rebase) | YES | | ||
| | #91 | feat/mcp-workforce | Track E (rebase; stacks on #92) | YES | | ||
| | **#87** | feat/proactive-agent-builder-persona | NEW: auto-merge — contains `parseInputsShape` `optional: true` regression fix that Track F depends on; the new persona JSON is additive | YES (verify fix still in branch first) | | ||
| | **#89** | codex/deploy-v1-readme | NEW: AUTO-MERGE for docs alignment | YES (nice-to-have; merges if green) | | ||
|
|
||
| Open cloud PRs handled: | ||
|
|
||
| | PR | Handled by | Auto-merge? | | ||
| |---|---|---| | ||
| | cloud#548 | Verified for trigger registration; paired with relaycron#5 | YES (after architectural items resolved — see below) | | ||
| | cloud#551 | Phase 3 dispatcher, already unblocked | YES | | ||
| | cloud#554 | Daytona meter | NO — platform-team gates on meter name; flag for Khaliq | | ||
| | cloud#555 | Workflow-invocations shim; Track J adds follow-ups | Merge #555 first, then merge Track J's follow-ups on top | | ||
|
|
||
| Open chain-branch PRs: | ||
|
|
||
| | PR | Repo | Auto-merge? | | ||
| |---|---|---| | ||
| | relay#843 | relay | YES | | ||
| | relaycron#5 | relaycron | YES (pair with cloud#548) | | ||
| | relayauth#39 | relayauth | YES (docs-only, low risk) | | ||
|
|
||
| ### cloud#548 special handling | ||
|
|
||
| cloud#548 still has my three architectural items unaddressed (deploy payload shape, URL scoping, OSS scope governance). Track C's coordination comment is posted. **The workflow's lead Claude must verify before auto-merging cloud#548**: | ||
|
|
||
| 1. **Payload shape resolved.** Track G adds a new endpoint at `/api/v1/workspaces/:id/deployments` taking persona+bundle, separate from #548's `/api/v1/deploy` taking single-file. Both coexist. ✅ Resolved by Track G shipping in parallel. | ||
| 2. **URL scoping** — #548 has top-level `/api/v1/deploy` while reads are workspace-scoped. Track G's new endpoint is workspace-scoped. The mixed shape is acceptable for v1 (legacy `/api/v1/deploy` deprecates later); proceed. | ||
| 3. **OSS scope governance** — relay#844 merged, packages live. Once relay#843 merges too, the cleanup PR to remove cloud/packages/agent-relay-{events,agent} can land. **The workflow should land cloud#548 as-is** (with the OSS packages still in cloud), then run a follow-up cleanup PR (Track L below) that removes them and pins to `^6.0.17`. | ||
|
|
||
| --- | ||
|
|
||
| ## Track N — Cloud sandbox token path-scoping (use `POST /v1/tokens/path`) | ||
|
|
||
| **Repo:** `$CLOUD_REPO.wt-token-paths` (worktree) | ||
| **Implementer model:** codex (medium reasoning). | ||
| **Working branch:** `feat/sandbox-token-path-scoped` | ||
| **Base:** post-relayauth#39 merged `main` (officially documented contract). cloud#548 ideally merged so agent-gateway is the consumer; can ship against `main` if #548 still in flight. | ||
| **Depends on:** relayauth#39 merged. Track G merged (Track N updates Track G's sandbox-provisioning flow to use path-scoped tokens). | ||
|
|
||
| **Allowed-dirty regex:** `packages/core/src/relayfile/client\.ts|packages/web/lib/proactive-runtime/.*|packages/web/lib/.*sandbox.*|services/agent-gateway/.*` | ||
|
|
||
| ### Why this exists | ||
|
|
||
| Today's `mintRelayfileToken` in `packages/core/src/relayfile/client.ts` issues sandbox tokens via the two-step `POST /v1/identities` + `POST /v1/tokens` flow with broad `relayfile:fs:read:*` / `relayfile:fs:write:*` scopes. Every deployed agent's sandbox can therefore read/write **the entire workspace VFS mount**, including paths unrelated to the persona's declared listeners. | ||
|
|
||
| relayauth implemented `POST /v1/tokens/path` in M1 (relayauth#38) for path-scoped token issuance — workspace-token auth in, `relay_pa_*` token out with scopes intersected to the requested path list. Documentation lands in relayauth#39. Cloud doesn't consume it yet. | ||
|
|
||
| This is **least-privilege hardening, not a functional blocker.** First deploy works without it; production hardening wants it. | ||
|
|
||
| ### Implementation | ||
|
|
||
| 1. **Add a new helper `mintPathScopedRelayfileToken`** in `packages/core/src/relayfile/client.ts`: | ||
|
|
||
| ```ts | ||
| export interface MintPathScopedRelayfileTokenOptions { | ||
| workspaceId: string; | ||
| relayAuthUrl: string; | ||
| workspaceToken: string; // user/workspace token authorizing the mint (NOT the relayAuthApiKey) | ||
| paths: string[]; // e.g. ['/github/pull_requests/**', '/linear/issues/**'] | ||
| ttlSeconds?: number; | ||
| agentName?: string; // for token labeling/audit | ||
| } | ||
|
|
||
| export async function mintPathScopedRelayfileToken( | ||
| opts: MintPathScopedRelayfileTokenOptions, | ||
| ): Promise<string> { | ||
| const url = normalizeBaseUrl(opts.relayAuthUrl); | ||
| const res = await fetch(`${url}/v1/tokens/path`, { | ||
| method: 'POST', | ||
| headers: { | ||
| 'content-type': 'application/json', | ||
| authorization: `Bearer ${opts.workspaceToken}`, | ||
| }, | ||
| body: JSON.stringify({ | ||
| workspaceId: opts.workspaceId, | ||
| paths: opts.paths, | ||
| ttlSeconds: opts.ttlSeconds ?? 3600, | ||
| agentName: opts.agentName ?? 'cloud-orchestrator', | ||
| }), | ||
| }); | ||
| if (!res.ok) { | ||
| throw new Error(`relayauth path-token mint failed: ${res.status} ${await res.text()}`); | ||
| } | ||
| const { accessToken } = await res.json() as { accessToken: string }; | ||
| if (!accessToken?.startsWith('relay_pa_')) { | ||
| throw new Error('relayauth returned token without expected relay_pa_ prefix'); | ||
| } | ||
| return accessToken; | ||
| } | ||
| ``` | ||
|
|
||
| Keep the existing `mintRelayfileToken` (broad-scoped) for legacy call sites — don't remove until all consumers migrated. | ||
|
|
||
| 2. **Update Track G's sandbox-provisioning flow** to use the new helper. When provisioning the Daytona sandbox in the persona+bundle endpoint: | ||
| - Derive `paths` from `persona.integrations.<provider>.triggers[]` → watch globs (the same translation Track G already does). | ||
| - Call `mintPathScopedRelayfileToken({ workspaceId, relayAuthUrl, workspaceToken, paths, agentName: persona.id })`. | ||
| - Inject the returned token as `RELAYFILE_TOKEN` (or whatever the runner expects) into the sandbox env vars instead of the broad-scoped token. | ||
|
|
||
| 3. **Migrate `services/agent-gateway/`** if it has its own minting path (verify via grep). The gateway likely uses `mintRelayfileToken` to bootstrap; if so, route through `mintPathScopedRelayfileToken` when the consumer is a deployed agent (not the workflow orchestrator). | ||
|
|
||
| 4. **Audit log** every path-token mint with `workspaceId`, `agentId`, `paths`, `requester`. Mirror the existing relayfile-token audit pattern. | ||
|
|
||
| ### Track N tests | ||
|
|
||
| - [ ] `mintPathScopedRelayfileToken` happy path: paths array → 200 with `relay_pa_*` token. | ||
| - [ ] Mock relayauth returning 403 / 4xx → wraps clean error. | ||
| - [ ] Mock relayauth returning malformed token (no `relay_pa_` prefix) → throws. | ||
| - [ ] Track G integration test: persona declaring `github.triggers[pull_request.opened]` results in a sandbox token whose scopes are `/github/pull_requests/**` only (not `*`). | ||
| - [ ] Legacy `mintRelayfileToken` callers still work (no regression). | ||
|
|
||
| ### Track N acceptance | ||
|
|
||
| - [ ] `mintPathScopedRelayfileToken` exported from `packages/core/src/relayfile/client.ts`. | ||
| - [ ] Track G's sandbox provisioning uses path-scoped tokens. | ||
| - [ ] Audit logging on mint. | ||
| - [ ] Legacy broad-scope helper still works for orchestrator-internal calls. | ||
| - [ ] PR title: `feat(security): mint path-scoped relayfile tokens for sandbox agents`. | ||
| - [ ] Auto-merge on gates green. | ||
|
|
||
| **Effort estimate:** ~2h. | ||
|
|
||
| --- | ||
|
|
||
| ## Track M — Cloud `@relaycron/*` pin bump (post-relaycron#5 merge) | ||
|
|
||
| **Repo:** `$CLOUD_REPO.wt-relaycron-bump` (worktree) | ||
| **Implementer model:** codex (low reasoning — pure dep bump). | ||
| **Working branch:** `chore/bump-relaycron-packages` | ||
| **Base:** post-relaycron#5 merged `main`. | ||
| **Depends on:** relaycron#5 merged (✅ 2026-05-12T21:32:06Z); `@relaycron/server@0.1.3` and `@relaycron/types@0.1.3` published (✅ 21:35 UTC). | ||
|
|
||
| ### Why this exists | ||
|
|
||
| Cloud's `packages/relaycron-cloud/` (workspace path `packages/relaycron/`) and `packages/relaycron-types/` consume `@relaycron/server` and `@relaycron/types` as npm deps pinned at `^0.1.0`. relaycron#5 merged at 21:32 UTC and published `0.1.3` of both packages with the WS-delivery + cancel API + buffered-ticks changes. The lockfile is pinned to the pre-#5 version, so the bump is needed for cloud to actually consume the new code. | ||
|
|
||
| This is separate from cloud#548's agent-gateway consumption — agent-gateway talks to relaycron over WS/HTTP via `services/agent-gateway/src/relaycron-client.ts`, not via the npm package, so it doesn't need this bump. | ||
|
|
||
| ### Preflight (already cleared at spec authoring time) | ||
|
|
||
| ```bash | ||
| # Both should pass; included for re-runs / future workflows. | ||
| RC5_MERGED=$(gh pr view 5 --repo AgentWorkforce/relaycron --json mergedAt -q '.mergedAt') | ||
| SERVER_VER=$(npm view @relaycron/server version) | ||
| TYPES_VER=$(npm view @relaycron/types version) | ||
|
|
||
| if [ -z "$RC5_MERGED" ] || [ "$RC5_MERGED" = "null" ]; then | ||
| echo "WAITING: relaycron#5 not merged"; exit 0 | ||
| fi | ||
| if [ "$SERVER_VER" != "0.1.3" ]; then | ||
| echo "NOTE: @relaycron/server resolved to $SERVER_VER, expected 0.1.3 — proceed with $SERVER_VER"; | ||
| fi | ||
| ``` | ||
|
|
||
| ### Implementation | ||
|
|
||
| 1. Bump these pins to `^0.1.3`: | ||
|
|
||
| | File | Pin | From | To | | ||
| |---|---|---|---| | ||
| | `packages/relaycron/package.json` | `@relaycron/server` | `^0.1.0` | `^0.1.3` | | ||
| | `packages/relaycron/package.json` | `@relaycron/types` | `^0.1.0` | `^0.1.3` | | ||
| | `packages/relaycron-types/package.json` (if pinned there too — verify via grep) | `@relaycron/types` | as-is | `^0.1.3` | | ||
| | root `package.json` (if pinned there — verify via grep) | both | as-is | `^0.1.3` | | ||
|
|
||
| 2. Run `npm install` to refresh `package-lock.json`. | ||
| 3. Run `npm run typecheck` — should stay clean (WS API additions are additive within `0.1.x`). | ||
| 4. Run `npm run relaycron:test` — passes. | ||
| 5. **Per workforce-publish-workflow memory: grep `.github/workflows/*.yml` for any references to `@relaycron/server` or `@relaycron/types` that need version bumps** (most likely none, but check). | ||
|
|
||
| ### Track M acceptance | ||
|
|
||
| - [ ] All `@relaycron/*` pins on the new published version. | ||
| - [ ] Lockfile refreshed. | ||
| - [ ] Typecheck + tests green. | ||
| - [ ] PR title: `chore(deps): bump @relaycron/{server,types} to <new-version>`. | ||
| - [ ] Auto-merge on gates green. | ||
|
|
||
| **Effort estimate:** ~20min (mechanical bump). | ||
|
|
||
| --- | ||
|
|
||
| ## Track L — Cloud OSS-scope cleanup (post-#548 merge) | ||
|
|
||
| **Repo:** `$CLOUD_REPO.wt-oss-cleanup` (worktree) | ||
| **Implementer model:** codex (medium reasoning). | ||
| **Working branch:** `chore/remove-agent-relay-packages` | ||
| **Base:** post-cloud#548 merged `main`. | ||
|
|
||
| ### Preflight — already cleared at spec authoring time | ||
|
|
||
| ```bash | ||
| # relay#843 merged + publish run 25763431116 completed at 21:49:38 UTC. | ||
| # All @agent-relay/* packages are at 6.0.18 on npm. | ||
| # This block is left for re-runs / future workflows. | ||
|
|
||
| LATEST=$(npm view @agent-relay/sdk version 2>/dev/null) | ||
| if [ -z "$LATEST" ] || [ "$LATEST" = "6.0.17" ]; then | ||
| echo "WAITING: @agent-relay/sdk publish hasn't propagated"; exit 0 | ||
| fi | ||
| echo "OK: @agent-relay/sdk at $LATEST" | ||
| ``` | ||
|
|
||
| ### Implementation | ||
|
|
||
| 1. Delete `cloud/packages/agent-relay-events/` and `cloud/packages/agent-relay-agent/` directories. | ||
| 2. Add `"@agent-relay/events": "^6.0.18"` and `"@agent-relay/agent": "^6.0.18"` to `services/agent-gateway/package.json` and any other consumer (verify via `grep -rln "agent-relay-events\|agent-relay-agent" services/ packages/`). | ||
| 3. Refresh `package-lock.json` via `npm install`. | ||
| 4. **Also bump other `@agent-relay/*` pins** in the workspace to `^6.0.18` for umbrella alignment — `@agent-relay/{config,credential-proxy,sdk}` on `main` are at `^6.0.13`; the chain branch already moved them to `^6.0.17`. Take them to `^6.0.18` so the workspace is consistent. | ||
| 5. Run typecheck + tests; verify agent-gateway service still builds against the OSS packages. | ||
| 6. **Per workforce-publish-workflow memory: grep `.github/workflows/*.yml` + `Makefile`** for any references to `agent-relay-events` / `agent-relay-agent` that need cleanup. | ||
| 7. PR title: `chore: remove in-tree @agent-relay/{events,agent}; consume from npm @ ^6.0.18`. | ||
|
|
||
| **Auto-merge?** YES on gates green. | ||
|
|
||
| **Effort estimate:** ~1h. | ||
|
|
||
| --- | ||
|
|
||
| ## What Khaliq sees when waking up | ||
|
|
||
| After the workflow completes (assuming no aborts), morning state: | ||
|
|
||
| **Merged on `main`:** | ||
| - Workforce: #87 (with input fix), #91, #92, #93, #94, #96, #97, plus 6 new Track D/F/H/I/K branches, plus #89 README (optional). | ||
| - Cloud: #548, #551, #555, plus 5 new Track A/B/G/J/L branches. | ||
| - Relay: #843. | ||
| - Relaycron: #5. | ||
| - Relayauth: #39. | ||
|
|
||
| **Open (intentional holds):** | ||
| - cloud#554 (Daytona meter — platform-team gates). | ||
| - Anything from "Out of scope" list. | ||
|
|
||
| **Ready for testing:** | ||
| - ✅ `workforce deploy ./examples/weekly-digest/persona.json --mode cloud` should work end-to-end against staging. | ||
| - ✅ Cloud deploy endpoint accepts persona+bundle. | ||
| - ✅ Schedules registered with relaycron; watches registered at agent startup with gateway DO. | ||
| - ✅ Sandbox provisions; runner executes; handler runs. | ||
| - ⚠️ Memory calls no-op (stub). | ||
| - ⚠️ Workflow.run MCP tool returns runIds for registered slugs (Track J's `echo` registered as proof-of-life). | ||
|
|
||
| **Smoke test result** in workflow log: | ||
| - `SMOKE_TEST: PASS` — weekly-digest deployed against staging; cron tick posted GitHub issue within 90s. | ||
| - OR `SMOKE_TEST: FAIL — <reason>` with logs. | ||
|
|
||
| **Loud holes (documented in every track PR body):** | ||
| - ⚠️ Memory not wired (`ctx.memory` is a stub). | ||
| - ⚠️ M3 destroy/list commands missing. | ||
|
|
||
| **What Khaliq does in the morning:** | ||
| 1. Read the workflow's final summary comment on cloud#553 (lists every merged PR + smoke test result). | ||
| 2. If smoke test passed: run `workforce deploy ./examples/review-agent/persona.json --mode cloud` against a personal GitHub repo, force-open a PR, watch the agent post a review. | ||
| 3. If smoke test failed: inspect logs, decide whether to revert or push fix. | ||
|
|
||
| ### What this workflow does NOT deliver | ||
|
|
||
| - Memory wiring (loud hole). | ||
| - M3 destroy/list CLI commands. | ||
| - `@workforce/daytona-runner` npm publish (separate agent). | ||
| - cloud#554 Daytona meter flip-to-ready (platform-team gates). | ||
|
|
||
| --- | ||
|
|
||
| ## Merge DAG — auto-merge order | ||
|
|
||
| The workflow's lead Claude walks this DAG topologically. Each node auto-merges when (a) it's opened/exists, (b) all its dependencies are merged, (c) CI green, (d) no `CHANGES_REQUESTED` reviews, (e) no merge conflicts. | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Add language identifiers to fenced code blocks (MD040).
Several fenced blocks are unlabeled; please add explicit languages (bash, ts, json, or text) to satisfy markdownlint and keep CI/docs checks clean.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 47-47: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 58-58: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 75-75: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 255-255: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 273-273: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 294-294: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 613-613: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 617-617: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 688-688: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 723-723: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 788-788: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1362-1362: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/plans/deploy-v1-schema-cascade-spec.md` around lines 47 - 1362, The
review flags unlabeled fenced code blocks (MD040) in
docs/plans/deploy-v1-schema-cascade-spec.md; add explicit language identifiers
to each triple-backtick fence (e.g. ```bash for shell snippets like the
HOME/ROOT block and gh commands, ```ts for TypeScript examples, ```json for JSON
bodies such as persona/bundle schemas, and ```text where generic text is
intended) so markdownlint passes. Locate every fenced block in the file
(examples: the initial HOME/ROOT block, PersonaSpec snippets, gh CLI snippets,
and JSON API contract examples) and update the opening fence to include the
appropriate language token, keeping the fence contents unchanged.
There was a problem hiding this comment.
♻️ Duplicate comments (1)
examples/weekly-digest/README.md (1)
60-62:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winEnvironment variable scope issue (duplicate).
The
RELAYFILE_MOUNT_ROOTvariable is scoped only toecho, not to the downstreamnodecommand. Thenodeprocess needs this variable to write to the Relayfile mount.🔧 Suggested fix
-RELAYFILE_MOUNT_ROOT=/path/to/mount \ -echo '{"id":"manual-1","workspace":"ws_demo","type":"cron.tick","occurredAt":"2026-05-12T09:00:00Z","name":"weekly","cron":"0 9 * * 6"}' \ - | node /tmp/wf-weekly-digest/runner.mjs +echo '{"id":"manual-1","workspace":"ws_demo","type":"cron.tick","occurredAt":"2026-05-12T09:00:00Z","name":"weekly","cron":"0 9 * * 6"}' \ + | RELAYFILE_MOUNT_ROOT=/path/to/mount node /tmp/wf-weekly-digest/runner.mjsOr use
export:+export RELAYFILE_MOUNT_ROOT=/path/to/mount echo '{"id":"manual-1","workspace":"ws_demo","type":"cron.tick","occurredAt":"2026-05-12T09:00:00Z","name":"weekly","cron":"0 9 * * 6"}' \ | node /tmp/wf-weekly-digest/runner.mjs🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@examples/weekly-digest/README.md` around lines 60 - 62, The RELAYFILE_MOUNT_ROOT environment variable is only applied to the echo command, so the downstream node process (runner.mjs) doesn't see it; fix by exporting RELAYFILE_MOUNT_ROOT (e.g., run "export RELAYFILE_MOUNT_ROOT=...") before piping to node or ensure the env is set for the node invocation as well so the node process can write to the Relayfile mount referenced by runner.mjs.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In `@examples/weekly-digest/README.md`:
- Around line 60-62: The RELAYFILE_MOUNT_ROOT environment variable is only
applied to the echo command, so the downstream node process (runner.mjs) doesn't
see it; fix by exporting RELAYFILE_MOUNT_ROOT (e.g., run "export
RELAYFILE_MOUNT_ROOT=...") before piping to node or ensure the env is set for
the node invocation as well so the node process can write to the Relayfile mount
referenced by runner.mjs.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 79c0af22-0ba4-4ac5-bf07-7c447d18564a
📒 Files selected for processing (18)
examples/weekly-digest/README.mdexamples/weekly-digest/agent.tspackages/runtime/src/clients/errors.tspackages/runtime/src/clients/github.test.tspackages/runtime/src/clients/github.tspackages/runtime/src/clients/index.tspackages/runtime/src/clients/jira.test.tspackages/runtime/src/clients/jira.tspackages/runtime/src/clients/linear.test.tspackages/runtime/src/clients/linear.tspackages/runtime/src/clients/notion.test.tspackages/runtime/src/clients/notion.tspackages/runtime/src/clients/request.tspackages/runtime/src/clients/slack.test.tspackages/runtime/src/clients/slack.tspackages/runtime/src/errors.tspackages/runtime/src/index.tspackages/runtime/src/types.ts
💤 Files with no reviewable changes (1)
- packages/runtime/src/clients/errors.ts
🚧 Files skipped from review as they are similar to previous changes (13)
- examples/weekly-digest/agent.ts
- packages/runtime/src/clients/linear.test.ts
- packages/runtime/src/types.ts
- packages/runtime/src/clients/linear.ts
- packages/runtime/src/clients/jira.ts
- packages/runtime/src/clients/slack.test.ts
- packages/runtime/src/clients/notion.test.ts
- packages/runtime/src/errors.ts
- packages/runtime/src/clients/request.ts
- packages/runtime/src/clients/github.test.ts
- packages/runtime/src/clients/index.ts
- packages/runtime/src/clients/notion.ts
- packages/runtime/src/clients/github.ts
khaliqgant
force-pushed
the
feat/integrations-vfs
branch
from
af8f4a2 to
2fa0ef9
Compare
khaliqgant
added a commit
that referenced
this pull request
May 12, 2026
Adds a thin, opt-in bridge between workforce's WorkforceCtx and the
@agent-assistant/proactive runtime-interop primitives that just shipped
in agent-assistant#91.
What ships
- packages/runtime/src/proactive.ts — two helpers:
- toProactiveSession(ctx, { agentId? }): maps a workforce ctx into the
RuntimeInteropSession descriptor agent-assistant session/memory/
scheduling primitives consume. Defaults agentId to ctx.agentName.
- schedulerBindingFromCtx(ctx): produces a ContextSchedulerBinding
that routes proactive wake-up requests through ctx.schedule.at /
ctx.schedule.cancel. Lets agent-assistant's proactive engine
schedule follow-ups using workforce's own schedule context.
- Re-exports ContextSchedulerBinding, RuntimeInteropSession,
RuntimeScheduleContext for callers building custom adapters.
- packages/runtime/src/proactive.test.ts — 4 tests covering session
shape, agentId override, schedule.at routing, schedule.cancel routing.
- packages/runtime/package.json — adds @agent-assistant/proactive
dependency (^0.4.31) and the ./proactive subpath export.
Why opt-in
- Workforce's runtime doesn't currently use agent-assistant/sessions for
stateful turn tracking — ctx is event-driven and stateless per
invocation. Handlers that compose with agent-assistant tooling import
these helpers; otherwise the runtime stays unchanged. When workforce
adopts session-scoped memory/scheduling, the wiring lifts up into
buildCtx so the bridge becomes implicit.
Notes
- Includes a one-line fix to examples/openclaw-routing.ts pulling
selection.runtime.* → selection.* per #95's PersonaSelection flatten.
Same fix applied by sub-agents on #92 / #94 rebases.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…t style
Switches workforce's integration clients from direct REST calls to the
Relayfile-VFS writeback pattern used by sage + the cloud workflows.
Handler-side surface (ctx.github.upsertIssue, ctx.linear.comment, etc.)
stays identical; the wire underneath flips from "speak HTTP to GitHub"
to "write a JSON draft inside the Relayfile mount and let the writeback
worker do the actual API call." Aligns workforce with the rest of the
org's integration story and inherits writeback durability + retry for
free.
Substrate
- packages/runtime/src/errors.ts (top-level): WorkforceIntegrationError
moves here with the { provider, operation, cause, retryable } shape
sage/cloud already use. Old clients/errors.ts is removed; the public
surface re-exports it from the same package import path so existing
consumers (mcp-workforce) keep compiling.
- packages/runtime/src/clients/request.ts: shared VFS helpers
(readJsonFile, readTextFile, listJsonFiles, listDirectoryEntries,
writeJsonFile + atomic write-then-rename) with mount-root path
validation and optional writeback-receipt polling.
Clients
- github.ts is rewritten as a VFS client. Same GithubClient interface
(comment, createIssue, upsertIssue, getPr, postReview); each method
now reads/writes files at canonical paths under
`/github/repos/<owner>/<repo>/...`.
- linear, slack, notion, jira ship as new typed clients with the same
pattern. IntegrationClients in types.ts now types all five concretely
instead of leaving four as unknown.
Tests
- github.test.ts is rewritten end-to-end against a tempdir mount.
- linear/slack/notion/jira tests run against tempdir mounts too.
- 29 runtime tests pass (up from 18), 386 across the repo.
Example
- weekly-digest/agent.ts drops the WORKFORCE_INTEGRATION_GITHUB_TOKEN
plumbing; the github client picks up RELAYFILE_MOUNT_ROOT instead.
- weekly-digest/README.md documents the writeback model + Relayfile
mount env requirement, and drops the GITHUB_TOKEN setup step.
Notes
- mcp-workforce (PR #91) imports createGithubClient with a different
construction shape today (`{ token }`); it'll need a follow-up
commit to switch to IntegrationClientOptions once this lands. The
MCP package depends on the new shape, not the old.
- The direct-REST github implementation that shipped in #90 is
replaced wholesale. No persona today depends on it; weekly-digest
is updated in this commit.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
khaliqgant
force-pushed
the
feat/integrations-vfs
branch
from
2fa0ef9 to
8b2ebe1
Compare
khaliqgant
added a commit
that referenced
this pull request
May 12, 2026
Ports the two example agents from the closed codex/deploy-v1-pr branch to the Relayfile-VFS integration-client style introduced in #92. review-agent - GitHub PR opened: pulls the diff via ctx.github.getPr, runs the persona's harness on the diff body, posts a review via ctx.github.postReview. - @mention in an issue/review comment: harness with the comment thread as context, posts the reply via ctx.github.comment. - check_run.completed (failure): harness with the failed CI logs as context, proposes a fix in a comment. - Slack app_mention: conversational reply via ctx.slack. linear-shipper - Linear issue created: clones the target repo into the sandbox, runs ctx.harness.run on the issue body, opens a draft PR via ctx.github, comments back on the Linear issue with the PR link. - Headless (no traits in the persona); demonstrates the paraglide "Linear issue → ship" pattern. Both examples adapt to the WorkforceProviderEvent shape — they read the raw provider payload from event.payload rather than treating the event as the payload itself. Tests: typecheck clean across the workspace and against examples/tsconfig.json (which path-maps @agentworkforce/runtime to the workspace source). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
added 2 commits
May 13, 2026 02:27
Track E1: Track E1 — rebase #92 (feat/integrations-vfs) See workforce/docs/plans/deploy-v1-schema-cascade-spec.md
- github.upsertIssue update: preserve number/state/html_url/url so the next call still finds the canonical issue file by number. - github.getPr: use the discovered pull directory segment verbatim instead of re-encoding it (avoids double-escaping slug paths like `123__fix%2Fci`). - request.waitForReceipt: short-circuit in fire-and-forget mode (timeoutMs <= 0) before reading the just-written draft, so a draft payload carrying top-level id/path/created is never reinterpreted as a writeback receipt. - jira.transition: validate that the transition id is non-empty after trimming, throwing a non-retryable WorkforceIntegrationError. - notion.createPage: throw WorkforceIntegrationError instead of a generic Error when parent.database_id is missing, matching the rest of the integration error contract. - weekly-digest README: move RELAYFILE_MOUNT_ROOT in front of `node` (was scoped only to `echo`) and add a prerequisite note that real GitHub writes require the Relayfile writeback worker to be running.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Spec reference
Source spec: workforce/docs/plans/deploy-v1-schema-cascade-spec.md
Track section: Track E1 — rebase #92 (feat/integrations-vfs)
Final signoff
Final gate (typecheck + tests)
Self-reflection report
Known gaps after this PR
Co-Authored-By: Ricky deploy-v1 schema cascade noreply@agentworkforce.com